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TOETC A. 2 - HT/T OPERATOR'S GUIDE 


I* INTRODUCTION 

The single program that controls NASIS vhen the MT/T 
version of that system is running is called the HT/T 
Monitor. The monitor is the only part of NASIS with which 
the HT/T Operator communicatee. 

To communicate with the monitor simply depress the ATTENTION 
key. The monitor will prompt you with a time-stamped 
question mark, for example: 

10:25 ? 

and unlock the keyboard. Note that while your keyboard is 
unlocked, NASIS is stopped. Waste no time in entering 
commands and never, never leave your terminal sitting with 
its keyboard unlocked. 


II. MONITOR COMMANDS 

The monitor commands are comprised of a command name and, in 
some cases, additional operands. The monitor, when reading 
commands, recogni-zes three ‘’special" characters — two 

delimiters: (separators between command names and/or 

operands) comma and blank, and a character which may enclose 
an operand to denote that that operand has •’special” 
characters within it: the quote mark. The delimiters 

beta ve slightly dif ferently--a string of contiguous blanks 
isinterpeted as one delimiter, but two contiguous commas 
are interpeted as two delimiters, and so forth. If you have 
to put blanks, commas or guotes within an operand, you must 
surround that operand with quote marks. In addition, if 
there are enclosed guotes, they must be paired inside the 
operand. For example 

*don'*t let this confuse you, it**s not really that 
difficult* 

is a valid quoted string containing embedded commas, blanks 
and quote marks. 

MSG NASISID,TEXT Sufficient Abbreviation 

(S , A. ) : M 

This command sends the message specified by the TEXT operand 
to the user who is on NASIS under the userid specified by 
the operand NASISID. Remember to surround the message text 
with quote marks if it contains commas, quote marks, or 
imbedded spaces. Example: 

M NEO 1 , * HERE * ' S A MESSAGE. * 


BCST TEXT 


S • A , : 


B 
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This command sends the message specified by the TEXT operand 
to all the users logged on to NASIS. Example? 

BC ’DATACELL IS DOWN NSIC not AV AIL ABLE . * 

FORCE NASISI D S.A.: F 

This command is used to terminate a NASIS user. The user 
(identified by NASISIE) is sent the message 
It*** TASK DELETED BY FORCE **♦" ana then logged off. 
Exam pie: 

F NEOl 

KILL NASISID S.A.: K 

This command is used when FORCE fails. The KILL command may 
be reentered several times. The user (if the KILL works) 
will receive a program interrupt five at location zero, so 
you may ignore the message abcut that event. Example: 

KI NEOI 

SHUTDOWN TIME S.A.: S 

This command terminates NASIS. The TIME operand specifies 
how long to wait before actually terminating the system 
(default is five minutes). If the time specified is zero 
minutes NASIS is terminated immediately. This zero-time 
shutdown should be used only when absolutely necessary 
because it doesn’t give warning to the users. Normally, 
both you and the users get a message stating the time-of-day 
wh® the system will shut itself down. Should you change 
your mind about the shutdown enter another shutdown to 
override the previous one. (Only the last SHUTDOWN command 
entered has any effect.) Example: 

S 30 (To terminate NASIS in a half-hour) 

LIMIT TERM,# S.A.: L 

This command allows you to limit the number of users of 
various sorts allowed on NASIS and to limit some of the 
resources of NASIS itself. The TERM operand is either a 
’’class" of NASISIDs (defined as the first two characters of 
the NASISID) or one of the keywords "USERS", "PRINTS", 
"SEARCHES", "SOFTS" or "RECORDS". The keyword "USERS" is 
used to limit the total number of users allowed on NASIS and 
is the default value assumed if TERM is omitted. Keyword 
"SEARCHES" limits the size of a set a NASIS user may search 
on, "PRINTS" limits the size of a set he may print and so 
on. If the TERM operand consists of exactly two characters 
it is assumed to be a class name and the number of NASISIDs 
of that class allowed on NASIS will be limited. If the TERM 
operand consists of any other number of characters than two, 
it is assumed to be a keyword or a part of a keyword. If 
the # operand is defaulted, the value 32767 is used. If the 
# operand is entered, TERM must be also entered, even if you 
use lust a comma to default it. Examples: 

LIMIT ,20 (Limit total number of users to 20) 

L S , 50 (Limit search set size to 50) 
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II NE,2 (Limit «NE" NASISIIS to 2) 

USERS S. A, *: U 

This command lists all the NASISIDs of the users currently 
using NASIS. Only those users completely logged on are 
listed, if there are users in the process of getting on, 
they will not show up on the list frcm a USERS* 

NUSEPS S. A. : N c/: N/: N/ 

This command tells you hew many users are currently using 
NASIS. Unlike USERS, this command also tallies the users 
who are in the process of logging on. 

NEWS "OFF” | TEXT S.A.: NE 

This command is used to control the sending and composition 
of the "news" which is sent to each user as he logs on to 
NASIS* Entering "OFF" as the operand terminates the sending 
of all news and deletes all the text from the news buffer. 
Entering anything but "OFF*' causes whatever you enter to be 
added as the last line to whatever is already in the news 
buffer. If you enter no operands at all to HEWS, it will 
add a carriage-return to the end of the news buffer. 
Exam pies: 

NEWS OFF (Kills the sending of news) 

NEWS ’THIS LINE WILL GC AT THE END OF THE BUFFER. 1 

STATS "ON/"OFF" S.A. ST 

When this command with operand OFF is encountered, the 
Monitor turns on an indicator tellinq NASIS not to take 
usage statistics. If ON is entered as the operand, that 
indicator is turned off. NOTE: this command may only be 

entered via the "NASIS. COMMANDS (0) " dataset. 
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COMMAND SUMMARY 


COMMAND 

OPERANDS 

FUNCTION 



MSG 

NASISID. TEXT 

Send message 

to specified user 

BCST 

TEXT 

Send message 

to all 

users. 

FORCE 

NASISID 

Get rid of a 

user* 


KIIL 

NASISID 

Really get rid cf a 

user. 

SHOT DOWN 

TIME 

Terminate NASIS, 


LIMIT 

TERM,# 

Limit NASIS 

users or resources 

USER S 


List current 

NASIS 

users. 

NUSERS 


Count current NASIS 

users. 

NENS 

♦’OFF" fTEXT 

Turn off or 

add to 

news text. 

STATS 

"ON” /"OFF” 

Set usage statistics mode. 
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TOPIC B.1 - CONVERSION , VALIDATION, A ED FCRBATTING 
ROUTINES 


I. INTRODUCTION 

The design of the NASIS system provides for three types 
of user-written routines to perform special processing 
unigue to a particular field, A "user" is a mainline 
programmer for the specific data base; such as the data 
base administrator. These routines are classified as 
conversion, validation and formatting. 

The DBPL/I statements used in the NASIS system provide 
for updating and retrieving from a data base. The data 
is always assumed to be character strings. The ability 
to specify Conversion, Validation and formatting 
routines is provided, allow for massaging field data 
and still meet the DBPL/I character string 
requirement , 

The Conversion routine is used to alter character 
string input to any desired form. The Validation 
routine is used either to verify the results of a 
Conversion routine or to verify the character string 
input. 

The Formatting routine is used to alter the internal 
stored data bach to a character string. 

A. CONVERSION Routine 

The CONVERSION routine is called by the data base 
executive, DBPAC, to convert the data passed by 
the user in a DBPL/I statement from an EBCDIC 
character string to some other type of 
representation fcr storage on a file. The 
CONVERSION routine is invoked by all DBPL/I 
statements that place data, by field name, onto 
the data base, 

B. VALIDATION Routine 

The VALIDATION routine is call of theed 
immediately after the call CONVERSION routine. 
The function of this routine is to verify data 
input for storage on the data base, via the rules 
specified by the user of this field. A VALIDATION 
routine may be present regardless of the presence 
of a CONVERSION routine. To assist in this 
evaluation, the NASIS system provides for a 
validation argument. 
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C. FORMATTING Routine 

The FORMATTING routine is called to change the 
data read from the data base into the desirable 
output fori. The FORMATTING routine is invoked by 
all DBPL/I statements that retrieve data, by field 
name, from the data base. The formatting routine 
specified for a field will be called whenever the 
data in that field is retrieved, 

A collection of "standard” conversion and 
formatting routines is provided in the DBEXITS 
module (Section IV, Topic B.4). 

CALLING SEQUENCE 

In general, these routines are called dynamically, by 
name. They rust have been link-edited with the current 
Retrieval system and be capable of accepting a PL/I 
formatted parameter list. 

A. CONVERSION Routine 

The format of the CALL statement used by DBPAC to 
invoke the CONVERSION routine is as follows: 

CALL rtnname (input-data, output-area, 

error-bit) ; 

where: 

"rtnname” identifies the particular routine 
to be called, as specified in the field 
descriptor. It is the routine's 
procedure name or an entry point. 

"input-data” is a varying lenqth character 
string, maximum lenqth equal to 4000, 
into which DBPAC has placed the input 
data value. 

"output-area” is a varying length character 
string, maximum length equal to 4000, 
initialized to null, into which the exit 
routine places the converted data 
value. 


"error-bit" is a bit switch, initialized to 
one (1) , which is set to zero (0) if 
there were no errors uncovered in the 
conversion, or cne (1) if errors were 
detected. The burden of setting the 
switch to zero (0) is with the 



PAGE 12 


CONVERSION routine. 

B. VALIDATION Boutine 

The format of the CALL statement used by DBPAC to 
invoke the VALIDATION routine is as follows: 

CALL rtnname (input-data, output-area, 

error-bit, argument) ; 

where: 

’•rtnname*’ identifies the particular routine 
to be called, as specified in the field 
descriptor. It is the routine’s 
procedure name or an entry point. 

"input-data" is a varying lencrth character 
string, maximum length equal to 4000, 
into which DBPAC places the input data 
value after conversion. 

"output-area" is a varying length character 
string, maximum lenoth equal to 4000, 
initialized to null, into which the exit 
routine places the validated data 
value. 

"error-bit" is a bit switch, initialized to 
one (1), which is set to 2 ero (0) if 
there were no errors encountered in the 
validation, or one (1) if errors were 
detected. The VALIDATION Boutine is 
responsible for setting this switch. 

"argument" is a varying-length character 
string, maximum length equal to 50, into 
which DEPAC places the validation 
arqument, as read from the appropriate 
field of the descriptor for this data 
field. 

C. FORMATTING Routine 

The format of the CALL statement used by DBPAC to 
invoke the FOB MATTING routine is as follows: 

CALL rtnname (input-data, output-area); 

where: 

"rtnname" identifies the particular routine 
to be called, as specified in the field 
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descriptors. It is the routine’s 
procedure name or an entry point. 

”input-data” is a varying length character 
string, maximum length equal to 4000, 
into which DEPAC places the data value 
read from the data base. 

"output-area” is a varying length character 
string, maximum length equal to 4000, 
initialised to null, into which the exit 
routine places the formatted data 
value. 


III. RESTRICTION S 

The routines must heed the following restrictions: 

A. The routine can not make any calls to DBPAC (i.e., 
it should not contain any EEPI/I statements). 

B. The routine is the lowest level module; i.e*, it 
does not call any other routines. 

C. The routine is written in PL/I and compiled with 
the same compiler as the Retrieval PL/I modules. 
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APPENDIX A, 

Diagnostic Messages and Codes Produced By the Conversion, 
Validation, and Formatting Routines. 

A. Diagnostic Messages 

CALL ERSOP: MODULE ******** CANNOT EE LOADED. 

This error message is generated if the module named 
cannot be loaded when called by DBPAC. Ignoring the 
situation and allowing the system to run may cause 
unpredictable results. 

The most probable reasons for this error are: 

1. failure on the part of the user to have the job 
library containing this program properly DDEFed. 

2. inconsistency between the name of the routine as 
specified in the descriptor file and the name 
actually used when writing the program. 

B. DBPAC Error Codes Associated Hith the Conversion, 
Validation, and Formatting Routines 

031 KEY FIELD FAILED CONVERSION. 

The data value passed to the CONVERSION routine, for 
the hey field of the data base, was fcund to be in the 
wrong format. 

032 KEY FIELD FAILED VALIDATION. 

The data value passed to the VALIDATION routine, for 
the key field of the data base, was found to be 
invalid. 

053 DATA FIELD FAILED CONVERSION. 

The data value passed to the CONVERSION routine, for a 
data field, was found to be in the wrong format. 

054 DATA FIELD FAILED VALIDATION. 

The data value passed to the VAIIDATION routine, for a 
data field, was found to be invalid. 
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APPENDIX B. 

Sample Validation Routine 

A ample VALIDATION routine is shown below. The function of 
the routine is to compare the input data value to each of 
the four byte entries carried in the validation arguments. 
If a match is found, the routine substitutes a numeric code 
for the input data value, resets the error bit to accept the 
field and returns to DBPAC. If no match is found, the 
routine returns to DBPAC with the error bit set to reject 
the field. 


/* THIS IS A VALIDATION ROUTINE FOR TEE OPERATION CODES: 
/* THE PARAMETERS PASSED ARE: 

/* A= THE INPUT STRING WHICH IS TO EE VALIDATED. 

/* JV= THE VALUE TO EE RETURNED AFTER VALIDATION. 

/* C= THE BIT SNITCH. *C' MEANS PASSED VALIDATION. 

/* *1» MEANS BAILEE VALIDATION. 

/* D= THE VALIDATION ARGUMENTS. 

/* D IS COMPOSED OF THE FOLLOWING CHARACTER STRING: 

/* * ADDEADDRCNGEFLDCIELRCELE * 

CHECKOP: PROCEDURE (A,B,C,D); 

DECLARE (A, B, D) CHARACTER (*) VARYING, /*PARA8ETERS . 

C BIT ( 1 > ; /^PARAMETERS-. 

ON ERROR GO TO OUT_DIRTY; 

DO I « 1 TO 21 BY 4; 

IF A = SUBSTR (D,I,4) 

THEN GO TO CUT_CLEAN; 

END; 

OUT_DIHTY: /* IF IT DOES NOT MATCH KEYWORDS IN ARGUMENT. 
C = * 1'B; 

RETURN; 

OUT_CLEAN: /* THE VALIDATION OF OP_CODE NAS SUCCESSFUL. 

C = * 0* B; 

B = A; 

RETURN; 

END CHECKOP; 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

V 

V 
*/ 

*/ 

*/ 


*/ 


*/ 
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TOPIC B.2 - DBPL/I LANGUAGE EXTENSION USER’S GUIDE 


I. INTRODUCTION 

This manual is for PL/I Programmers writing a mainline 
program that accesses a BASIS data base. The data base 
organization being used is fullv specified in the 
"NASIS Overview”. 

All data base access is done by a combination of: 

1, an extension of the PL/I language, called 
DBPL/I, for data base access, 

2, a compilation-time source program processor, 
DB, and 

3, execution-time routines DEPAC and DBLIST. 

This manual is the specification of the DBPL/I 
language extension and is the reference manual to the 
DB preprocessor. Detailed specification of the 
internals of the DB preprocessor are given in Section 
IV, Topic B.1 of the DBB , and the details on the 
execution-time routines are given in the DBPAC Design 
Specifications (Section IV, Topic E.2 of the DWB) . 
Neither of these two sections are needed for writing, 
compiling and executing mainline programs; they may be 
needed for debugging. 

Chapter II of this manual discusses the usage of the 
DB preprocessor. Chapters III through VI are composed 
of discussions and examples of the different features 
of DBPL/I and their interrelationships. Chapter VII, 
"Buies and Syntactic Descriptions", provides a detailed 
reference to specific information in alphabetical 
order. Appendix A is a guick reference to DBPL/I 
syntax. 

II. THE PREPHOCESSOR 
A. Overview 

DBPL/I language statements have to be processed 
at compilation- time . The processing consists of 

syntax analysis and the generation of PL/I 
statements CALLing DBPAC tc accomplish what the 
DBPL/I statements signify. This processing is 
done by the preprocessor stage of the PL/I 
compiler under control of a preprocessor procedure 
named DB, A prcarammer using DBPI/I does not have 
to write the DB preprocessor or be concerned with 
the PL/I statements that are generated by it; but 
he is required to write certain statements in his 
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source program so that the DB preprocessor is 
properly invoked hy the PL/I compiler for his 
program. He must also refrain from using certain 
identifiers which are reserved words for the DB 
preprocessor’s exclusive use. 

B. Usage 

The statements required tc properly invoke the DB 
preprocessor are illustrated in an example program 
in Figure 1. 

1. FIG 1: PBOCEDUFE OPTIONS (PEE NT PS NT) ; 

2. %~INCLUD£ IISEMAC(DE); 

3. DECLARE REPORT# CHARACTER (13) VARYING ; 

4. 

5. DB ({ ON EBROPFILE (STAB) GO TC NOTE? )) 

6 . 

7. DB (( 

8. READ FILE(STAB) KE7 (' 67N26508') ; 

9. GET FILE (STAB) FIELD( ' REPTNC') INTO (BEPOBT#) ; 

10 . )) 

11. PUT DATA (BEPOBT#); 

12. BETUBN ; 

13. 

14. NOTES PUT DATA (STAB. CNCODE) ; 

15. DONE; DE <( FINISH; )) 

16. END FIG_1 ; 

X INCLUDE (DB); 

One XINCLUEE DB statement must he written 
immediately following the external PROCEDOBE 
statement of the compilation. Any PROCEDURE 
statement attributes could have been used in line 
1, The X INCLUDE DB statement must precede all 
other statements such as line 3. 

DB ( (ON ERROBFILE (STAB) GO TO NOTE;)) 

Any DBPL/I statement, such as this ON statement, 
mast be written as a sutarqument in a DB 
preprocessor function reference. As many DB 
statements may be used as required. Any PL/I 
statements required may be used at lines 3, 4, 6, 
and 11-14. Lines 7-10 illustrate that more than 
one DBPL/I statement may be written in one DB 
statement. However, no non-DEPL/I statements 
would be permitted within a D8 function 
reference. 


DB( (FINISH;) ) 
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One DBPL/I FINISH statement must be written 
following all other C/E statements in the 
compilation. It will usually be written -just 
preceding the ENE statement of the external 
procedure because it generates a FETUFN statement. 
If the statement in line 14 is executed, then the 
procedure will be terminated by control passing 
sequentially to the RETURN statement Generated for 
line 15. The label in line 15 is not required, 
but it would be valid as shown (e.g., line 12 
could be: GO TO DONE;). 

The DB preprocessor function oenerates diagnostic 
comments {see Section III, Topic B. 1 of the 
DNB) . When reviewing a compilation, the 
programmer should first find the summary 
diagnostic message (DBC67) to know how many error 
diagnostics for which to search. 

C. Reserved Words 

The FINISH ON-condition is reserved for use by the 
DB preprocessor. The following identifiers are 
reserved for the uses specified in this manual or 
for the DB preprocessor *s use: 

CC1I ST 
CPIIST 
DB 

DBEFCBP and all other identifiers beginning 

* DB * 

DUFLIST 

ERRORFILE 

tFIElD 

DBPL/I file-names 

FINISH 

LIST 

#LIST 

LISTERS 

ULIST 

DPLIST 

#XREF 

The PL/I HIGH and NULL built-in function names may 
be used as such in the program, but the names must 
not be otherwise declared. 

III. DATA BASE AND FILES 

A. Overview 

The DBPL/I language provides statements that 
enable data to be transmitted between internal 
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main storaqe and external storage devices 
organized as one or more data bases, 

B. Data Sets 

Each "data set" is a named, labelled collection of 
related data, subdivided into keyed data set 
records. 

The one "descriptor data set" for a data base 
stores data describing the information data set<s) 
and their interrelationships. It is a collection 
of one or more descriptor reqions. 

Each "descriptor region" is a collection of 
descriptor records for an information data set. 
The first record in a descriptor region is a data 
set descriptor record. Subsequent records in a 
descriptor region are field descriptor records, 

C, Files 

DBPL/I requires a file name to be used for a file, 
What data set (s) a file name represents is deduced 
from the file title. Characteristics of a file 
may be described with keywords, called file 
attributes, specified for the file name, deduced 
contextually, or assumed by default. 

A "file name" is an identifier specified in the 
FILE clause of DEPL/I statements. A file name mav 
not exceed the seven-character length limitation 
for external names. The user must execute a PL/I 
ALLOCATE statement for the HFCB before executing 
any DBPI/I statements, Eor example, to use a 
DBPL/I file-name "plex" the following statement 
must be executed: 

AL1CCATE PLEX; 

Of course the allocation must be done in a program 
in which PLEX will be automatically declared 
because of its use in a DBPL/I statement. If the 
module where the ALLOCATE is to be done does not 
otherwise need DBPL/I statements, the following 
are recommended as a minimum: 

% INCLUDE LISBKflC(DE); 

ALLOCATE PLEX; 

DBUCN E5B0PFI1H (PLEX) SYSTEM;)) 

DB ( {FINISH;) ) 

A "file title" can be specified for a DBPL/I file 
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either through the file name or through the 
character string value of the expression in the 
TITLE option of a EBPL/I OPEN statement. If a 
file is OPENed implicitly, or if no TITLE option 
is specified in the OPEN statement that causes 
explicit opening of the file, the file title is 
assumed to be the same as the file name. 

A file title, not beginning with a pound sign {#) , 
consists of a six-character left-aligned dataplex 
identification and a one-character suffix. Which 
data set(s) the file name represents will be 
deduced from the file title suffix value as 
follows: 

blank: the identified data base or anchor 

data set (for physical record 
operations: GET RECORD or WRITE) . 

numeric: the particular associated data 

set. 

Z-G: the particular subfile data set. 

A-P: the particular index data set. 

A pound sign <#) , prefixed to a file title, 
specifies that a file name represents the 
descriptor region rather than the information data 
set itself. (This combination may be specified 
only in the TITLE option of a DBPL/I OPEN 
statement because it results in an eight-character 
title.) If the eighth character of a descriptor 
region title is blank, the file represents only 
the anchor descriptor region. This facility 
allows mainline programs to create, maintain or 
retrieve from descriptor regions for their own 
purposes. 

File ♦’attributes’’ for a file name may be 
specified explicitly in a EEPL/I OPEN statement or 
assumed by default. Different attributes may be 
applied in different openings of the same file in 
a program; at any particular time, the attributes 
applied by the most recent opening apply to the 
file name. 

D. File Level Statements 

DBPL/I provides the OPBN, CLOSE and ON ERSOPFILE 
statements for file level operations. All are 
optional; a simple mainline may not need any of 
them. There is nc statement for declaring a 
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DBPL/I file; the DE preprocessor generates the 
necessary Hainline File Control Block (HFCB) 
automatically. 

The OPES and CLOSE statements may be used for any 
of the purposes indicated in their descriptions in 
Chapter VII of this manual. 

The OS ERRORFILE statement is used to establish a 
user’s error routine in the mainline to which the 
DBPAC execution routines will return when an error 
condition (e.q., key not found) occurs on a file. 
Several OS statements for a file may be executed 
in a program either before or after the file is 
opened. 

An "error routine” must heqin with a statement 
label (the same label identifier specified in an 
OS statement) • PL/T (or DEE1/I) statements may be 
written following the label to handle the error. 
These statements may reference certain fields in 
the WFCE for assistance in determining the error 
identity and resumina normal execution. MFCB 
fields are referenced using a qualified name 
consisting of the file name and an MFCB field 
name. The MFCB fields that may be referenced in a 
file exception routine are as follows; 

file-name. ONCODE is a binary integer whose 
value specifies the exceptional 
condition. The meanings of the various 
ONCODE values are in Section III, Topic 
B.3 of the DSB. 

file-name. ONFIIE is the current file title. 

file-name. ONFIELD is the current field name 
(when applicable) * 

file-name. ONEETURN is a label variable set by 
DBPAC. 

An error routine may be terminated in any manner; 
for certain of the less serious ONCODEs, a GO TO 
file-name. ONRETURN; statement may be used which 
transfers control to the statement following the 
one that raised the exceptional condition. 

For a more generalized exception routine for one 
or more files, the relevant EFCP fields may be 
referenced using a Qualified name consisting of 
the reserved keyword ERFOREILE and an MFCB field 
name; e.o., ERRORFIIE. ONCODE. 
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RECORDS 

A. Overview 

The data items in a data set are arranged in data 
set records. In this manual, a ’’physical record” 
means a single data set record having an internal 
self-def inino, variable-length format, a 
fixed-length internal Key# and the other data 
items. 

The simple term, "record”, in this manual means 
either a logical record or a physical record, 
depending on content. 

The "current record of a file" is the single 
record having the key value established by the 
most recent record level operation on the data 
base component file. It is accessible only by 
DBPL/I statements; the mainline has no means of 
addressing it. In a spanned index, the "current 
record" is actually a "region” of one or more 
physical records made to behave like one logical 
record. 

E. Record Level Statements 

DBP1/I provides the LOCATE, READ, and UNLOCK 
statements for record level operations. The 
record level statements cause a record (possibly 
more than one physical record) to be transmitted 
between the data set (s) and the current record of 
a file. The transmission may be immediate (READ 
or UNLOCK after update) and/or subsequent (LOCATE 
or READ for update) . 1CCATE and REAE cause 
automatic file openinq, if necessary. 

The LOCATE statement is used to create a new 
current record having a new key for subsequent 
transmission to the file (no WRITE statement is 
needed). The LOCATE SUBFILE statement is used to 
create a new current subrecord. 

The REAE statement is used to retrieve a record 
from a file and establish it as the current record 
of the file. If the record is updated, it is 
subsequently retransmitted to the file (no REWRITE 
statement is needed). The READ SUBFILE statement 
is used to retrieve a subrecord and BEAD INDEX to 
retrieve an index record. 

The UNLOCK statement releases a locked current 
record so that other tasks can read it. If the 
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record was updated, it is re transmitted to the 
file. The UNLOCK SUBFILE statement releases a 
locked current subrecord. 

C. Physical Record Statements 

DBPL/I provides the GET BECORD and WRITE 
statements for physical records. These are 
special purpose statements intended for use in a 
utility mainline fcr backing up, restoring or 
reorganizing one particular data set at a time. 
They may be used only bv the owner of the data 
base. 

The GET RECORD moves the current physical record 
without change to the user's receiving field (for 
backup purposes). 

The WRITE statement transmits a physical record 
from the mainline without change to a data set 
(for restoring or reorganizing purposes) . WRITE 
causes automatic file opening, if necessary. 

FIELDS 

6. Overview 

The data items in a record are arranged in fields 
and, optionally, field elements. 

A "field" is a data item having a field name, an 
internal field descriptor and one or more values 
per record. Since some fields may have multiple 
values per record, an individual data item is 
called a field element. This section of the 
manual relates primarily to anchor, associated and 
subrecord fields, although the GET INDEX KEY 
statement may be used for index kev fields. 
Facilities for subfile control fields and for the 
list-of-keys field in index records are discussed 
in Chapter VI of this manual. 

A "field name" is an eiqht-character string value 
identifying a field. A mainline written in terms 
of a known particular data base may use a 
character-string constant in string quotes. A 
more generalized mainline may use an 
eight-character strinq variable and assign a value 
to it from input data or from a descriptor record 
before using it as a field name. The names of the 
fields in field descriptor records are given in 
the Descriptor File Specification, 
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An "internal field descriptor" is either a field 
descriptor record in a descriptor region (for data 
base fields) or an internal descriptor (for 
descriptor fields ). The descriptor record for an 
anchor field may limit GET access of a FIELD to 
those users the file owner has authorized. (POT 
and REPOT may be used only by the file owner). 

A "field element value" is always a varying length 
character string value in the mainline. 
(Internally, it may be fixed- or variable-length 
and character or ceded form.) There may be some 
transformation between the internal value and the 
mainline value. If the field descriptor names an 
input validation and/or conversion routine or an 
output formatting routine, the relevant routines 
will be invoked automatically when the field is 
accessed. 

The internal value of a field element is null 
until a value is POT into it. A GET FIELD 
statement retrieves a value even if it is null; a 
null value yields a null mainline string value 
(unless a formatting routine translates a null 
internal value to something ncn-null such as *N0 
DATA YET* ) . To handle such a case, the most 
general way to retrieve field values is as 
follows: 

DO 1=1 TO Hay (#FIELE (mf cb, fldname) , 1) ; 

DB ( (GET FILE (mfeb) FIELE (f ldname) INTO (var) ;) ) 

IF LENGTH (var) =0 

THEN GO TO FIELD_EYH & USTED ; 

/♦Use field element value in var.*/ 

END; 

FIELD_EXHAUSTED: 

DO not attempt GET FIELD more than #FIELC times or 
something like *N0 DATA YET* will be retrieved 
after values actually present. The mainline may 
determine if the field element is null by testing 
if the length of the mainline string is zero. A 
REPOT statement replaces an element with a new 
value which may be a null value. 

Field Level Statements and Functions 

DBPL/I provides the PUT FIELD, GET FIELD and REPOT 
statements for the creation, retrieval, and 

maintenance of field elements on anchor and 
subfile records. *FIE1D is a PL/I function 
provided for obtaining the numbers of elements in 
a field. The field level statements cause one or 
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more field elements to he transmitted individually 
between the current record of a file and a 
mainline prooram. A record level statement mast 
have been executed to establish a current record 
of the file before a field level statement may be 
executed* 

The POT FIELD statement is used to create a new 
field element in the current record of the file. 
It is subsequently transmitted to the file 
automatically (no WRITE or REWRITE statement is 
needed) « 

The GET FIELD statement is used to retrieve a 
field element from the current record of the 
file. 

The REPOT statement is used to replace an existinq 
primary field element in the current record of the 
file. It is subseauently retransmitted to the 
file automatically (no REWRITE statement is 
needed) . 

The #FIELD function calculates the number of 
elements in a field. It may be used to govern 
GETting of elements or merely to determine if a 
field has any elements or net. 

For a field that may not have multiple elements, 
the field level statements transmit the single 
field element value. 

The following discussion applies to fields that 
may have multiple elements. POTting an element 
appends it to the right end of the field. GETting 
of a FIELD element proceeds from left to right 
and, when the end of the field is passed, null 
values are generated. REPOTting an element 
replaces the ^current element of the field” which 
is the element most recently obtained by a GET 
FIELD from the current record of the file. There 
is no facility for referring to an element bv its 
position (subscript) in the field. If it is 
necessary to (re) GET an element that is to the 
left of the current element, the record may be 
(re) READ, resetting all of the internal current 
element counters to the first element of the 
fields. If it is necessary to maintain field 
elements in some order depending on their mainline 
values (rather than the order in which they are 
entered), the following technique may be used (for 
ascending sequence) : 
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DECEASE (OLD, NEW) CHARACTER (maxlen) VARYING; 
NEW - expression; 

DB READ FILE (name) (positioning); 

NEXT ELEMENT; 

GET FILE (name) FIELD (fieldname) INTO (OLD); 

)) ; 

IF LENGTH (OLD) /* IF OLD IS NON-NULL */ 
THEN DO; 

IF OLD > NEW /* GREATER THAN*/ 

THEN DO; /*INSEBT ELEMENT */ 

DB ( (RIPUT FILE (name) 

FIELD (fieldname) FROM (NEW) ; )); 
NEW = OLD; /* FOB PROPAGATION */ 
END; 

GO TO NEXT_ELEMENT; 

END; 

DB (< POT FILE (name) FIELD (fieldname) FROM 
(NEW); )); 

C. Index Field Retrieval 


DBPL/I provides a special GIT INDEX KEY statement 
and the #XREF function for retrieval from index 
records. (Such records may not be explicitly 
created or maintained by mainline programs) . A 
READ INDEX statement must have been executed to 
establish a current record of an index before a 
GET INDEX KEY or tXREF may be executed. 

The GET INDEX KEY statement is used to retrieve 
the index key field value from the current record 
of the index. 

The iXREF function calculates the number of cross 
references (anchor cr subfile key elements) in the 
current record (region) of the index. 

The GET FIELD statement and tFTELD will not work 
on index record fields. An index record RECLEN 
field cannot be retrieved (it doesn't mean much in 
a spanned index) . The GET INDEX KEY statement is 
provided for the index key field, iXREF is 
provided (instead of #FIFLD) for "the cross 
reference field element count. The GET INDEX LIST 
SET statement (see section VI. B fcelcw) retrieves 
the whole cross reference list (instead of an 
element at a time). 


VI. II STS 


A 


Overview 
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A "list" of keys is a collection of ascending 
internal key elements in main storage, identified 
by a mainline list pointer, (The keys are 
accessible only by D8PL/I statements), 

A "list pointer" is a EL/I pointer variable 
declared in the mainline, set by a DBPL/I GET SET 
statement or LIST fnncticn reference, and used to 
identify a list. A list pointer having the PL/I 
NULL pointer value identifies a null (emoty) 
list. 

Under OS, 'main storage* for key lists consists of 
a large randomly accessible file. The list 
pointer addresses a control block, held in real 
memory, which describes the list. 

There are several ways to form lists (see Figure 

D : 

1. Bead anchor records sequentially and nick 
keys, 

2. Bead subrecords sequentially from a subfile 
and pick keys, 

3. Copy an index record cross reference list. 


4. Copy a subfile control field. 


5. 

Merqe 

the 

subfile 

control fields from a 


series 
list , 

of 

anchor 

records specified in a 

6. 

Merge 

the 

parent 

keys from a series of 


subrecords 

specified 

in a list. 


7, Get keys sequentially from a list and nick 
interesting cnes, 

8, Drop the duplicate keys from a list, 

9, Get internal keys sequentially from a list 
and qenerate internal keys for an output 
list, 

10. Logically combine (AND, OB, or AND NOT) 
compatible lists. 

The number of keys in a list may be found. Key 
elements (in external or internal form) may be 
taken from a list. A list may be used to control 
READing of anchor records. The mainline may 
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request and qet control cf any errors in the use 
of lists* 

Method 1: forming a list of anchor keys; 
ptr=NULL; 

— >EB{ (BIAD FIXE (plex) file-positioning;)) 

1 DB ( (GET FILE(plex) KEY SET(ptr);)) 


the GET KEY SET may or may not be executed 
depending on the result of GET FIELD statements, 
etc. 

Method 2: forming a list of subrecord keys: 
ptr=NULL; 

— >DB|(FEAD FILE(plex) SUBFILE {scfn) 
j file-positioning;)) 

j DE ( (GET FILE (plex) SUBFILE (scfn) 

| KEY SET (ptr) ;) ) 


It is analogous to method 1. 

Method 3: 

DB<{NEAD FILE (plex) INDEX (if n) 
file-positioning; ) ) 

DB ( (GET FILE (plex) INDEX (ifn) 

LIST SET (ptr) ;) ) 

It may be used on any index. 

Method 4: 

DE ( (READ FILE (plex) file-positioning;)) 

DB ( (GET FILE (plex) SUBFILE (scfn) LIST 
SET (ptr) ;) ) 

It copies the multi-element control field as a 
list of those subrecords in a subfile that are 
dependent on a particular anchor record, i.e. a 
"chain" of related detail records. Note that a 
control field is essentially a stored copy of the 
result of a whole-subfile search for a particular 
parent key value. 

Method 5: 

ptr2=CCLIST (plex, scfn, Ctrl) ; 

It is like method 4 repeated for all the keys in a 
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Index list with the results all CRed together; It 
produces a Complete Children List, 

Method 6; 

ptr2=CPLIST(plex,ptr1) ; 
or 

ptr2=0PLIST (plex,ptrl) ; 

It reads all the safe records in a list gett ing the 
parent key field from each one and merging the 
parent keys into the output list* The Unique 
Parent List function drops duplicate parent keys; 
Complete Parent List does not. 

Method 7: 


ptr2=NULL; 

— >DB((GET LIST (ptrl) KEY < (n) > INTO (var);)) 
| EE ((GET LIST (ptr 1) KEY SET(ptr2);)> 


Where the GET KEY SET may or mav not be executed 
depending on the "var" value. Method 7 
essentially handles a special case of method 1 
when the "file-posit ioninq" would be governed by a 
given list and only the key field would be gotten 
to determine selection; for such a case, method 7 
is far more efficient because no record level data 
base I/C is needed. 

Method 8; 

ptr2 = ULIST(ptrl); 

It efficiently produces a new list of unique keys 
(no duplicates) without any record level data base 
I/O, 

Method 9: 


DB ( (SET LIST (ptr 2) SIZE (dim) 
LIKE LIST (ptr 1) ;) ) 

>DE ( (GET LIST (pt.rl) INTERNAL KEY 

| INTO (var);)) 

J -->DB ( (POT LIST(Ptr2) INTERNAL KEY 
It FROM (expr);)) 

I 


It is a very special purpose variation of method 
7* It works with unconverted external key values. 
If the inner locp is used, it is possible to 
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generate more tban one key for each GET KEY. 
Since the output list may receive a multiple or a 
fraction of the number of keys in the input list, 
a site dimension must be supplied in the SET LIST 
LIKE LIST statement estimating the minimum number 
of output keys. 

Method 10: 


M* 

ptr3=LIST (ptrl , *£' ,ntr2) ; 

i _ « 


The LIST function forms a new list in main storaqe 
from two compatible lists in main storaqe. The 
two argument lists remain accessible for further 
combination or other use. The LIST function is 
used in retrieving for compound queries. Given 
two lists, A and B, the LIST operations provided 
are illustrated in Figure 2, "Venn Diagram." 

When more than two lists have to be combined, the 
mainline may use one of the following techniques 
(where P is the resultant intersection list) : 

T 1 = LIST (A, •£• , B) ; 

T2 = LIST (T 1 , * &• , C) : 

DB (( FREE LIST (T1))); /+IF DESIRED HEBE*/ 

R = LIST (T2, »S» , C) ; 

DB f< FREE LIST (T2) )); /*IF DESIRED HERE*/ 

A second possible technique is: 


B 

= LIST 


* £ * * 

B) 

R 

= LIST 

(B, 

*6*, 

C) 

R 

= LIST 

fB, 

•S', 

D) 


A third possible technioue is: 

B = LIST ( LIST (A, »S», B) , »S«, LIST (C, 
•e*, D)>; 

The last two techniques do not retain intermediate 
lists. 

List Statements and Functions 

#LIST is a PL/I function provided for obtaining 
the number of keys in a list. For example, if L 
is a pointer identifying a list and s is a 
varying-length character string, the following 
DO-group would be valid: 
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DO I - 1 TO #11 ST {1} ; 

DB (( GET LIST (I) KEY INTO (S) ; ))? 

PUT SKIP LIST (I, S) ; 

END ; 

If it is merely desired to determine if a list has 
any elements cr net, the following tecfcniaue is 
more efficient than a #LIST function reference: 

IF L -.= NOIL THEN /* LIST HAS HOPE THAN ONE 
ELEHENT */; 

The GET IIST KEY statement moves a list element 
key from a list tc the user’s receiving string. 
Any conversion from internal to external form is 
done automatically. The GET LIST INTEPNAL KEY 
statement never converts the list element key 
value. 

The REAL statement with the LIST file positioning 
option is used to read the anchor or subfile 
record with the next element of a list as its key. 
It is more efficient than GET LIST KEY; BEAD by 
KEY because the internal form of the key element 
is available for use without conversion. 

There are two independent "current elements of a 
list"; the one most recently obtained by a GET 
LIST KEY statement and the cne most recently used 
by any READ statement under control of the LIST. 
A key may be referred to sequentially forwards or 
backwards or by its position (subscript) in a 
list. The GET or REAL current element counter mav 
be reset by a GET LIST KEY (0) or a READ LIST 
KEY (0) statement respectively. 

The SET LIST, LIKE IIST, and POT LIST INTERNAL KEY 
statements are for allocating and posting lists 
for special purposes. 

An explicit FREE LIST statement frees the storage 
and NULLs the pointers for the lists specified. A 
general FREE LIST statement frees all current 
lists but does not NULL any pointers. 

The ON LISTEREOR statement is used to establish a 
user’s list exception routine in the mainline to 
which the list processing rentines return when an 
exceptional list condition occurs (e.g., 
attempting to combine incompatible lists). Use of 
the statement is optional and several ON LISTERROR 
statements may be executed in a program. 
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A "list exception routine" must becrin with a 
statement label (the same label identifier 
specified in an ON statements . PL/I (or DBPL/I) 
statements may be written following the label to 
handle the exceptional condition. These 
statements may reference a binary inteqer field 
named LISTEBB.ONCOIE (declared automatically by 
the DB preprocessor) for assistance in determining 
the exceptional condition, 

A list exception routine may be terminated in any 
manner; no provision is made for returning to the 
function reference that raised the exceptional 
condition. 

VII. PULES AND SYNTACTIC DESCBIPTICNS 

The syntax notation used in this manual is a subset of 

that used in the OS PL/I Deference Manual (Form 

C28-8201-0) and specified in Section A thereof. 

1. A notation variable is shown in lower case 
letters, hyphens and, possibly, a digit. All such 
variables shown are defined in this manual either 
syntactically or semantically. 

2. A notation constant denotes the literal occurrence 
of the characters shown. It consists either of 
all capital letters or cf a special character such 
as a colon, percent sion, parenthesis, comma or 
semicolon. 

3. Braces, {} # denote that a choice is to be made. 

4. Corner brackets, <> , denote options. Anything 

enclosed in brackets may appear one time or may 
not appear at all. 

5. The vertical stroke, J , indicates that a choice 
is to be made. 

6. An ellipsis, ... , denotes that the contents of 

the preceding brackets may optionally occur more 
than once in succession. 
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* The CCLIST Function* 

Couplets Children LIST builds a list of subrecord keys from 
a given parent key list, for a particular subfile, and 
returns a pointer value identifying the new list to the 
point of invocation. The new list is the complete list of 
dependent subrecords (children) formed by merging the parent 
record* s subfile control field lists. Any previously 
current record and subrecords that were updated will be 
transmitted to the data base* The record identified by the 
last (highest) key in the given list will remain as the 
current (but net locked) record; any current subrecords or 
index records will remain current. The BEAD cursor of the 
given list will be reset. 

Reference: 

CCLIST (file-name, ctlfield, parent-list-pointer) 

A CCLIST function reference is used as or in an expression; 
it is not to be a sobargument in a DB preprocessor function 
reference. The user may not declare any attributes for the 
CCLIST function; the following statement will be generated 
automatically: 

DECLARE CCLIST ENTRY (, CB AR (8) , PTR) RETURNS (PTR) ; 

Argu ments; 

file -name: specifies the data base file from which parent 
records are to be transmitted. It may not be an OUTPUT 
file. If the file is net open, it will be opened 
automatically. The •file-name* must be used in at least one 
DBPL /I statement elsewhere in the program. 

ctlfield: is an expression that specifies the name of the 
subfile control field. The value of the expression is 
converted to a character strino, if necessary, the first 
eight characters of which identify tke control field. 

parent-list-pointer; must be a pointer expression that 
identifies a list in main storage of parent keys from the 
data base accessed by 'file-name*. It must have been set 
when the CCLIST function is invoked. 

Result: 

The value returned bv the CCLIST function is a pointer 
identifying the new complete children list. The new list 
will be in order of ascending internal subrecord key values 
without duplicated values. If none of the parent records 
have any dependent subrecords in the subfile, a NULL pointer 
value will be returned. 
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*Tha CLOSE Statement* 

The CLOSE statement closes a file ty disassociating a file 
name from the self-describing data set with which it was 
associated by an OPEN, It may also specify that the file be 
erased. 

General Format; 

CLOSE FILE (file-name* <EBASE> <, FILE (file-name) 

<ER ASE>>. * • ; 

Syntax Rules; 

1. The CLOSE statement must be a subargument in a DB 
preprocessor function reference. 

2. Several files can be closed by one CLOSE 
statem ent. 

Gene ral Rules; 

1. A closed file can be reopened. 

2. Closinq an unopened file, or an already closed 
file, has no effect unless ERASE is specified. 

3. If a file is not closed by a CLOSE statement, it 
is automatically closed at the completion of the 
program in which it was opened, 

4. If the current record and/or subrecords were 
LOCATEd or updated, closinq will cause them to be 
transmitted to the data base, unlocked (if 
locked), and disestablished as the current 
record (s) of the file. 

5. The ERfiSE specification causes the file to be 
erased and uncatalcgued. If the file is a 
descriptor file, the descriptor reqion is erased. 
If the file is an anchor file, the whole data base 
but not its descriptors is erased. If the file is 
an associated file, a subfile or an index file, it 
is erased independently. ERASE is only valid for 
an UPDATE file. 
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'The CPLIST Sanction * 

Complete Parent LIST builds a complete list of parent record 
keys from a given subrecord (children) key list and returns 
a pointer value identifying the new list to the point of 
invocation. The new list has the same number of parent keys 
as the number of subrecord ID keys in the given list. 
Parent keys will fce repeated if mere than one of the given 
sufcrecord keys are dependent on a particular parent 
record. The subrecord identified by the last (highest) key 
in the given list will remain as the current (but not 
locked) subrecord of that subfile; any current or index 
records or subrecords of other subfiles will remain current. 
The HEAD cursor of the given list will be reset. 

Reference; 

CPLIST (file-name, child-list-pcinter) 

A CPLIST function reference is used as or in an expression; 
it is not to be a subargument in a EE preprocessor function 
reference. The user may net declare any attributes for the 
CPLIST function; the following statement will be generated 
auto mat ically; 

DECLARE CPLIST ENTRY (,PTF) RETUF NS (PTE) ; 

Arguments: 

file-name; specif ies the data base file from which subrecords 
are to be transmitted. It may not fce an OUTPUT file. If 
the file is not open, it will be opened automatically. The 
file-name must be used in at least one DBEL/I statement 
elsewhere in the program. 

child-list-pointer: must be a pointer expression that 

identifies a list in main storaqe of subrecord keys from the 
data base accessed by file-name. It must have been set when 
the CPLIST function is invoked. 

Result; 

The value returned by the CPLIST function is a pointer 
ideitifying the new complete parent list. The new list will 
be in order of ascending internal parent key values and may 
have repeated values. If the given subrecord list is null, 
a NULL pointer value will be returned. 
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•The BB Preprocessor Function* 


DB analyzes a DEPL/I data base access statement during 
compilation and generates, in its place, suitable PL/I 
statements for communication with DBPAC. Diagnostic 

comments may also be generated. 

Reference: 

<label:>. . , BB (<«label: ... subaroument > . ..)) 

1. One t INCLUDE (DE) preprocessor statement must 
have been executed by the FI/I compiler before any 
DE preprocessor function reference is made in a 
compilation, 

2. Several DB preprocessor function references may be 
made in a compilation. 

3. A DB preprocessor function reference may be made 
only between PL/I statements. 

4. Shen a single DBPI/I statement is to be used as 
the THEN-unit or FLSE-unit of a PL/I IF statement, 
the unit must be a PL/I DO-END qroup enclosing the 
DB preprocessor function reference. 

5. One or more label prefixes may precede a DB 
preprocessor function reference. They will 
identify the first executable statement generated 
for the first subargument. 

6. One FINISH statement must be executed by the PL/I 

compiler as the last sufcargument of the last DB 
preprocessor function reference after all other DB 
preprocessor function references in a 

compilation. 

Argument: 

1. The argument of a DE preprocessor function 

reference is a character string delimited bv 
double enclosing parentheses. Several 

subarguments can appear in the argument. Each 
must be a data base access statement having its 
own terminating semicolon. Blanks and comments 
may be used freely, as in PL/I, but no PL/I 
statements are permitted. 

2. • One or more label prefixes may precede a 

subargument. They will identify the first 

executable statement generated for the 
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subarqument 
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•The DUPLIST Function’ 


DUPL 1ST builds, in dynamically allocated main storage, a 
compressed copy of a list of keys and returns a pointer 
value identifying the new list to the point of invocation, 

Refe rence: 

EUPEIST (list-pointer) 

A EUPLXST function reference is used as or in an expression; 
it is not to be a subargument in a EE preprocessor function 
reference. The user may not declare any attributes for the 
DUEL 1ST function; the follcwinq statement will be generated 
automatically; 

EECLARF DOPIIST ENTRY (POINTER) FETOFNS (POINTER) ; 


Argu ment : 

list-pointer; must be a pointer expression that identifies a 
list of keys in main storage. It must have been set when 
the DOPLIST function is invoked. 

Resu It; 

The value returned by the EUPLIST function is a pointer 
identifying the compressed list copy. A compressed list has 
none or more list segments of maximum size followed by the 
last or only list segment allocated to exact length for the 
remaining keys and all segments are exactly filled; thus, it 
occupies the least possible main storage. 
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'Tie #FIELD Function* 


♦FIELD calculates the number cf elements in a field in the 
current record or subrecord of a file and returns it to the 
point of invocation. 

Reference: 

♦FIELD {file-name, field-name) 

A IFIELD function reference is used as cr in an expression; 
it is not to be a subarguroent in a IF preprocessor function 
reference. The user may net declare any attributes for the 
♦FIELD function; the follovinq statement will be generated 
automatically; 

DECLARE tFIELD ENTRY < , CHARACTER (P)) RETURNS (FIXED 
BIN (31) ; 


Arguments; 

file-name: identifies a data base file. It may not be an 
OUTPUT file. A current record or subrecord of the file or 
a subfile must have been established by a DBPL/I READ 
statement when the ♦FIELD function is executed. several 
♦FIELD function references may be executed on a current 
(sub) record of a file. 

field-name; is an expression that specifies the name of the 
data base field tc be examined. The value cf the expression 
is converted to a character string, if necessary, the first 
eight characters of which identify the field. Any field may 
be examined. 

Result; 

The value returned by the ♦ FIELD function is a binary 
integer of maximum precision giving the number of elements 
in the field in the current (sub) record of the file. If the 
field has a null value, a zero value will be returned. 
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•The FINISH Statement* 


The FINISH statement causes the EE preprocessor to complete 
its analysis of all data base access statements and its 
generation of suitable PL/I statements. A RETHRN Statement 
will be generated which will terminate execution of the 
procedure. A C1CSE is also generated for those file-names 
utilized by the compilation. Diagnostic comments may also 
be generated. 

General Format: 

FINISH; 

Syntax Rule: 

One FINISH statement must be used after all other data 
base access statements in a compilation. It must be 
the last subargument in a DE preprocessor function 
reference. 
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•The FREE LIST Statement* 

The EREE LIST statement frees main storage previously 
dynamically-allocated for one or more lists of 
{cross-reference) keys. 

General Format: 

FREE LIST < (list-pointer< ,list-pcinter> ...)>; 

Syntax Rules: 

1. The FREE LIST statement must be a sufcargument in a 
DB preprocessor function reference* 

2. Several lists may be explicitly freed by one FREE 
LIST statement. 

General Rules: 

1. If a list-pointer is explicitly specified, it must 
be a pointer expression that identifies a list of 
keys in main storage. It must have been set when 
the FREE LIST statement is executed. 

a. If the value of the list-pointer is NOLI., no 
action will be taken for that list pointer. 

b. If the value of the list-pointer is not NOLL, 
the dynamic main storage for the list of keys 
identified by it will be freed and the 
list-pointer will be given a NULL pointer 
value. 

c. FREE LIST will ignore a pointer which 
addresses a list which has been posted in 
SETAB and assiqned a set number. No action 
will be taken. 

2. If no list-pointer is explicitly specified in the 
FREE LIST statement, all dynamic list storage will 
be freed. The user’s list pointers are not given 
NULL values; it is the user’s responsibility not 
to use them for list identification until they are 
reset. If no dynamic list storaoe has been 
previously allocated, this option of the FREE 
LIST statement will have no effect. 
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•The GET FIELD Statement* 

The GET FIELD statement moves a data element value from the 
current record or subrecord of a file to the user*s 
receiving field; it may cause the value to be converted from 
an internal form to a display form. 

General Format: 

GET FILE (file-name) FIELD (field-name <, field-name> ... ) 

INTO (variable <, variable 2 ... ); 


Syntax Buies: 

1. The GET FIELD statement must be subargument in a 
DB preprocessor function reference. 

2. Several data element values can be moved by one 
GET FIELD statement. In this case, a 
corresponding variable must be specified for each 
field name. 

General Hules: 

1. The data element value will be taken from the data 
base file specified in the FILE clause. It may 
not be an OUTPUT file. 

2. A current record or subrecord of the file or a 
subfile must have been established by a BEAD 
statement when the GET statement is executed. 
Several GET FIELE statements may be executed on a 
current (sub)reccrd cf the file. 

3. The field-name is an expression that specifies the 
name of the data base field from which the data 
element value is to be obtained. The value of the 
expression is converted to a character string, if 
necessary, the first eight characters of which 
identify the field. If the user who executes the 
GET FIELD statement is net the owner of the file, 
the field-name may not specify a field that the 
owner has not authorised the user to GET. 

a. If the field is not subdivided into elements, 
the data element value (possibly null) will 
be taken from the field in the current record 
of the file. 

b. If the field is a multiple-element field, the 
data element value will be taken from the 
next element of the field, in left to right 
order, following the element taken by the 
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previous GET cf the FIEID of the current 
record of the file. If there has been no 
previous GET of the FIEID since the record 
was BEAD, the leftmost element is taken 
unless the field is null, in which case, a 
null element value will be generated. If a 
previous GET of a FIEID since the record was 
BEAD took the last (rightmost) element, a 
null value will be generated. 

The variable in the INTC clause specifies the 
user’s receiving field. It must be the identifier 
of a varvino length character string variable 
declared by the user. The internal form of the 
data element value will be taken as a varying 
length character string (cf zero length, if the 
value is null) , converted to display form and 
assigned to the variable. If the length of the 
dispiav form of the value exceeds the 
user-declared maximum length of the variable, the 
value will be truncated and an error condition 
raised. 
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1 The GET INDEX KEY Statement* 


The GET INDEX KEY statement moves the key value from the 
current record of an index to the user's receiving field; it 
may cause the value to be converted from an internal form to 
a display form. 

General Format: 

GET FILE (file-name) INDEX (indfield) KEY INTO (variable) ; 
Syntax Rule: 

The GET INDEX KEY statement must be a subargument in a 

EB preprocessor function reference. 

General Rules: 

1. The FILE clause specifies the data base file from 

which an index key value is tc be taken. It may 

not be an OUTPUT file. 

2. The INDEX clause specifies the index file from 

which the current index key value is to be taken. 

The indfield expression value is converted to a 
character string, if necessary, the first eight 
characters of which identify the indexed field. 

3. A current record of the index must have been 
established by a RFAD INI EX statement when the 
GET INDEX KEY statement is executed, 

4. The variable in the INTO clause specifies the 
user's receiving field. It must be tbe identifier 
of a varying length character string variable 
declared bv the user. The internal form of the 
index key value will be taken as a varying lenqth 
character string, converted to display form and 
assiqned to the variable. If the length of the 
display form of the value exceeds the 
user-declared maximum length of the variable, the 
value will be truncated and an error condition 
raised. 
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* The GET KEY SET Statement* 


The GET KEY SET statement moves the internal key value from 
a current record or subrecord of a file to a list of kevs in 
dynamically allocated main storage and sets a pointer 
identifying the list or extends an existent list* 

General Format: 

GET FILE {file- name) <S DEFILE (ctlfield)> KEY SET 

(list-pointer) ; 

Syntax Rule: 

The GET KEY SET statement must be a subargument in a DB 

preprocessor function reference* 

General Rules: 

1. The FILE clause specifies the data base file from 
which a key value is to be taken. It may not be 
an OUTPUT file. 

2a» If no SUBFILE clause is present, the internal kev 
value will be taken from the current root 
record. 

b. A SUBFILE clause specifies that the internal key 
value from a current sutreccrd is to be taken. 
The ctlfield expression value is converted to a 
character string, if necessary, the first eight 
characters of which identify the control field. 

3, A current (sub) record must have been established 
by a READ or READ SUBFILE statement when the GET 
KEY SET statement is executed, 

4. The list-pointer in the SET clause specifies the 
user’s pointer identifying the list of kevs in 
main storage. It must be the identifier of a 
pointer variable declared by the user. 

4a. If the user assigns the RUIL value to his 
list-pointer before executing the GET KEY SET 
statement, main storage will be dynamically 
allocated automatically for a new list, the kev 
value will be moved there from the current 
(sub) record, and the list-pointer value will be 
set to identify the list in main storage. The 
list remains allocated in main storage until the 
user executes a FREE LIST statement. 
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Otherwise, the list- pointer should identify a list 
of keys in main storaqe to which another 
compatible key value is tc be appended. It must 
have been set (by the user assigning NULL and 
executing a GET KEY SET statement as described 
above) when this GET KEY SET statement is 

executed. The key value will be moved from the 
current (sub) record. The list-pointer will be 
unchanged. 
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•The GET LIST INTERNAL KEY INTO Statement' 

The GET LIST INTERNAL KEY INTO statement increments the 
internal GET cursor of a list of keys in main storaqe 
identified by a list pointer and moves the indicated key 
value in internal form to the user's receiving field. 

General Format? 

GET LIST {list pointer) INTERNAL KEY INTO (variable) ; 
Syntax Rule: 

The GET LIST INTERNAL KEY INTC statement must be a 

subarguraent in a DB preprocessor function reference. 

General Rules: 

1. The list-pointer must be a pointer expression that 
identifies a list of keys in main storage from 
which the next kev value is to be taken. It must 
have been set when the GET LIST INTERNAL KEY INTO 
statement is executed. In the exceptional case of 
a list pointer having a NOLL pointer value, a null 
string value will be generated. 

2. The internal GET cursor of the list will be 
incremented to indicate that the next element of 
the list, in order of ascending internal key 
values, is current and will be taken. (If the 
internal GET cursor was reset, the element having 
the lowest internal key value is current and will 
be taken. If the internal GET cursor was on the 
last element (hiqhest internal key value), the 
cursor will be reset and a null string value will 
be generated.) 

3. The variable in the TNTC clause specifies the 
user's receiving field. It must be the identifier 
of a varying length character string variable 
declared by the user. The internal form of the 
key value will be taken as a varying length 
character string (cf zero length on end of list) 
and assigned without formatting to the variable. 
If the lenqth of the internal form of the value 
exceeds the user-declared maximum length of the 
variable, the value will be truncated and an error 
condition raised. 
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•The GET LIST KEY (0) Statement* 

The GET LIST KEY (0) statement resets the internal GET cursor 

of a list of keys in main storage. 

General Format: 

GET LIST (list-pointer) KEY (0) ; 

Syntax Pule: 

The GET LIST KEY (0) statement must be a sobargument in 

a DB preprocessor function reference. 

General Buies: 

1, The list-pointer must be a pointer expression that 
identifies a list of keys in main storage whose 
GET cursor is to be reset. The list-pointer must 
have been set 'when the GET LIST KEY (0) statement 
is executed. In the exceptional case of a 
list-pointer having a NOLL pointer value, no 
action will occur and no error condition will be 
raised, 

2, The internal GET cursor of the list will be reset 
(as it was when the list was built) . 
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•The GET LIST KEY INTO Statement* 

The GET LIST KEY INTO statement increments or sets the 
internal GET cursor of a list of keys in main storage 
identified by a list pointer and moves the indicated kev 
value to the user’s receiving field; it may cause the value 
to be converted from internal to display form. 

General Format: 

GET LIST (list-pointer) KEY <(rel-key)> INTO (variable); 
Syntax Rule: 

The GET LIST KEY INTO statement must be a sufcargument 

in a DB preprocessor function reference. 

General Rules: 

1, The list-pointer must be a pointer expression that 
identifies a list of keys in main storage from 
which the key value is to be taken. It must have 

been set when the GET LIST KEY INTO statement is 
executed. In the exceptional case of a list 
pointer faavinq a NOIL pointer value, a null string 
value will be generated. 

2a. If no rel-key is specified, the internal GET 
cursor of the list will be incremented to indicate 
that the next element of the list, in order of 
ascendinq internal key values, is current and will 
be taken. (If the internal GET cursor was reset, 
the element bavinq the lowest internal key value 
is current and will be taken. If the internal GET 
cursor was on the last element the cursor will be 
reset and a null string value will be generated.) 

fc. If a rel-key expression is specified, its value 
will be converted, if necessary, to a fixed binary 
integer of maximum precision. 

If rel-key has a neqative value, such as -1, the 
internal GET cursor of the list will be 
decremented to indicate that the previous element 
of the list, in order of internal kev values, is 
current and will be taken. (If the internal GET 
cursor was reset, the element havino the highest 
internal key value is current and will be taken. 
If the internal GET cursor was on the first 
element, the cursor will be reset and a null 
strinq value will be generated.) 

If rel-key has a positive value, the internal GET 
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cursor of the list will fc€ set to indicate that 
rel-key the relative element cf the list is 
current and will be taken. (If rel-key is zero or 
greater than the number of keys in the list, the 
cursor will be reset and a null string value will 
be generated.) 

The variable in the INTO clause specifies the 
user’s receiving field. It must be the identifier 
of a varying length character string variable 
declared by the user. The internal form of the 
key value will be taken as a varying length 
character string converted to display form and 
assigned to the variable. If the length of the 
display form of the value exceeds the 
user-declared maximum lenqtb of the variable, the 
value will be truncated and an error condition 
raised. 
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•The GET LIST KEY SET Statement* 

The GET LIST KEY SET statement moves the current internal 
key value from a list of keys identified by a list pointer 
to a new list in dynamically allocated main storage and sets 
a pointer identifying the new list or extends an existent 
list* 

General Format: 

GET LIST (list-pointer) KEY SET (new-list-pointer) ; 
Syntax Bale: 

The GET LIST KEY SET statement must te a subargument in 

a DB preprocessor function reference. 

General Buies: 

1. The list-pointer must be a pointer expression that 
identifies a list of keys in main storage having a 
non-zerc GET cursor indicating a current key. 

2. The internal key value will be taken from the 

current element of the list indicated hy the 

internal GET cursor. The GET cursor will be 

unchanged. 

3. The new-list-pointer in the SET clause specifies 
the user's pointer identifying the new list of 
keys in main storage. It must be the identifier 
of a pointer variable declared bv the user. 

3a. If the user assigns the NULL value to his 

new-list-pointer before executing the GET LIST KEY 
SET statement, main storage will be dynamically 
allocated automatically for a new list, the key 
value will be moved there, and the 
new-list-pointer value will he set to identify the 
new list in main storage. The new list remains 
allocated in main storage until the user executes 
a FBEE LIST statement. 

3b. Otherwise, the new-list-pointer should identify a 
list of keys in main storage to which another 
compatible key value is tc be appended. It must 
have been set when this GET LIST KEY SET 

statement is executed. The key value will be 
moved and the new-list-pointer will be 
unchanged * 
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•The GET LIST SET Statement* 

The GET LIST SET statement moves a list cf keys from the 
current record of an index cr from a subfile control field 
in the current root record to dynamically allocated main 
storage and sets a pointer identifying it. 

General Format: 

GET FILE (filename) CINCEX (indf ield) >LTST SET (list-pointer) 

<SUBFILE (ct If ield) > 


Syntax Buie: 

The GET LIST SET statement must be a subarqument in a 

DB preprocessor function reference. 

General Buies: 

1. The FILE clause specifies the data base file from 
which the list of keys is tc be taken. It may not 
be an ODTPDT file. 

2a. If an INDEX clause is specified, a current index 
record must have been established by a BEAD INDEX 
statement when the GET INDEX LIST SET statement is 
executed. The INDEX clause specifies the index 
file frcm which the list of (cross-reference) keys 
is to be taken. The indfield expression value is 
converted to a character string, if necessary, the 
first eight characters cf which identify the 
indexed field. 

2b. If a SUBFILE clause is specified, a current root 
record must have been established by a BEAD 
statement when the GET II ST SET statement is 
executed. The ctlfield expression value is 
converted to a character string, if necessary, the 
first eight characters of which identify the 
control field from which the list of keys 

(children) is to be taken. If the user who 
executes the GST SUBFILE LIST SET statement is not 
the owner of the file, the ctlfield may not 
specify a control field that the owner has not 
authorized the user to GET, 

2c. If neither an INDEX nor a SUBFILE clause is 
specified, the FILF must be an INPUT file opened 
with a TITLE for independent access to a 
particular inverted index file and a current 
record must have been established by a BEAD 
statement when the GET IIST SET statement is 
executed. The list of (crcss-ref erence) keys will 



PAGE 53 


be taken* 

The list-pointer in the SET clause specifies the 
user’s pointer to be set to identify the list of 
keys in main storage. It must he the identifier 
of a pointer variable declared by the user. 

a. If the list cf keys field of the current 
record is null, the list-pointer will be 
given a NOLI pointer value. {This occurs for 
the SUBFILE case when the control field is 
null indicating nc subordinate (children) 
subrecords. ) 

b. otherwise, main storage will be dynamically 
allocated automatically for the list, the 
list of keys will be moved there from the 
current record, and the list-pointer value 
will be set to identify the list in main 
storage. The list remains allocated in main 
storage until the user executes a FREE LIST 
statement. 
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♦The GET RECORD Statement* 

The GET RECORD statement moves a physical record in internal 
form from the current record of a file to the user*s 
receiving field. 

General Format: 

GET FILE (file-name) BICCFD INTO (variable); 

Syntax Rule: 

The GET RECORD statement must be a subarqument in a DB 

preprocessor function reference. 

General Rules: 

1. The physical record will be taken from the current 
record of the file specified in the FILE clause. 
It must be an UPDATE or INPUT file owned by the 
user who executes the GET RECORD statement. 

2. A current record of the file must have been 
established by a READ statement when the GET 
statement is executed. Several GET statements may 
be executed on a current record of the file. 

3. The variable in the INTO clause specifies the 
user*s receivinq field. It must be the identifier 
of a structure or fixed-length character string 
variable declared by the user. The internal 
self-defining physical record will be moved into 
the variable without any conversion. No receiving 
field length checking will be done. (A GET FIELD 
♦RECLEN* statement may be used for this purpose.) 
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•The % INCLUDE LISRHAC (DB) Preprocessor Statement* 

The % INCLUDE LISBBAC (DB) preprocessor statement causes the 
text of the DB preprocessor function tc be taken from the 
system source litrarv during compilation, incorporated in 
the source program and activated. 

General Format: 

* INCLUDE LISRHAC (DB) ; 

Syntax Buie: 

Only one % INCLUDE DE preprocessor statement may be 
used in the source text for a compilation. It must 
immediately follow the beginning PFCCEDUBE statement, 
before any other statements, if the compilation 
contains DB preprocessor functicn references for data 
base access statements. 
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’The LIST Function' 

LIST derives a new list of (cross-reference) keys from two 
given lists of keys and returns a pointer value identifying 
the new list to the point of invocation. The new list may 
be the union or intersection of the given lists or the 
sutlist of the first given list excluding the second. 

Beference: 

LIST (list-pointer-1, operator, list.-pointer-2) 

A LIST function reference is used as cr in an expression; it 
is not to be a subargument in a EE preprocessor function 
reference. The user may not declare any attributes for the 
LIST function; the following statement will be generated 
automatically; 

DECLARE LIST ENTRY (POINTER, CHARACTER ( 1) , POINTER) 
RETURNS (POINTER) ; 


Arguments; 

Each of the two list-pointer arguments must be a pointer 
expression that identifies a list of keys in main storaae. 
Each must have been set when the LIST function is invoked. 
The lists of keys identified must be compatible (having the 
same internal key element lenqth, etc.). 

The operator argument is an expression that specifies the 
list operation tc derive the new list. The value of the 
operator will be converted, if necessary, tc a one-character 
string. The value must be; 

logical OB, *,*, specifying the union, 

logical AND, *6', specifying the intersection, or 

minus sign, specifying the sublist of the first 

list excluding the second list. 

Result; 

The value returned by the LIST function is a pointer 
identifying the new list. The new list will be in order of 
ascending internal key values without duplicated key values 
(unless there are duplicates in one of the argument lists) * 
If the new list is null, the value returned may be assigned 
to one of the argument list pointers; however, the argument 
list would then be lost to the mainline (unless the user had 
assigned its pointer value tc another pointer previously) 
and could not be explicitly freed (but FREE LIST; would free 
it and all other lists). 
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•Tie #LIST Function* 

#LIS T calculates the number of (crcss-reference) keys in a 
list of keys identified by a list pointer and returns it to 
the point of invocation. 

Reference: 

#LIST (list-pointer) 

A # IIST function reference is used as or in an expression; 
it is not to be a subargument in a DB preprocessor function 
reference. The nser may not declare any attributes for the 
#LIS T function; the following statement will be generated 
automatically: 

DECLARE IIIST ENTRY (PC INTER) RETURNS (FIXED 
BINARY (31) ) ; 

Argument: 

The list-pointer argument must be a pointer expression that 
identifies a list of keys in main storage. It must have 
been set when the #LI5T function is invoked. 

Result: 

The value returned by the #LIST function is a binary integer 
of maximum precision giving the number of keys in the list 
identified by the list-pointer argument. If the 
list-pointer has a NULL pointer value, a zero value will be 
retu cned. 
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'The LOCATE Statement' 

The locate statement, which applies to OUTPUT or DIRECT 
UPDATE files, causes formation of a pew current record 
having a key field and having all ether fields null; it may 
also cause transmission of the previously current record to 
the data base. 

General Format: 

LOCATE FILE (file-name) KEYFROM (expression); 

Syntax Rule: 

The LOCATE statement must be a subarqument in DB 

preprocessor function reference. 

General Rules; 

1, The FILE clause specifies the data base file to 
which the record is to be subsequently 
transmitted. It oust be owned by the user who 
executes the LOCATE statement. It may not be an 
INPUT or SEQUENTIAL UPDATE file. 

2, If tbe file is not open, it is opened 

automatically. 

3, The value of the expression in the KEYFBOM clause 
is converted to a varying length character string, 
if necessary, validated and/or converted to an 
internal form. 

a. If the file has the SEQUENTIAL OUTPUT 

attributes, the internal key is checked for 
ascending sequence and subsequently used as 
the key of the record when it is transmitted 
to the data base. 

b. If the file has the DIRECT attribute, a READ 

KEY is attempted usinq the internal key. If 
the key is found, a duplicate key error 
condition is raised and the IOCATE statement 
has the effect of the READ KEY statement. If 
the key is not found, it is subsequently used 
as the key of the record when it is 

transmitted to the data base. 

4, After execution of the LOCATE statement, 

subrecords may be IOCATEd and values may be PUT 
into fields (other than the key) of the record for 
subsequent transmission to the data base, which 
will occur immediately before the next LOCATE, 
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READ, C10SE or automatic close operation on the 
file. 
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'The LOCATE SUBFILE Statement' 

The LOCATE SUBFILE statement causes formation of a new 
current subrecord having a key field and a parent keyfield 
and having all other fields null; it also causes the new kev 
to be automatically entered in the parent record control 
field; it may also cause transmission of the previously 
current subrecord of the subfile. 

General Format; 

LOCATE FILE (file-name* SOBFIIE (ctlfield) ; 

Syntax Buie; 

The LOCATE SBEFILE statement must be a subargument in a 

DB preprocessor function reference. 

General Buies; 

1. The FILE clausa specifies the data base file to 
which the sufcrecord is to fce subsequently 
transmitted. It must be owned by the user who 
executes the LOCATE SUBFILE statement. It may 
not fce an INPUT file. 

2. A current record of the file must have been 
established whan the LOCATE SUBFILE statement is 
executed. Several LOCATE SUEFIIE statements for 
one or more subfiles may fce executed on a current 
record cf the file. 

3. The ctlfield is an expression that specifies the 
name of the subfile control field. The value of 
the expression is converted to a character string, 
if necessary, the first eight characters of which 
identify the control field. 

i|. After execution of the ICCATE SOEFILE statement, 
values may fce POT into fields of the subrecord for 
subsequent transmission to the data base, which 
will occur immediately before the next LOCATE 
SUBFILE or BEAD SUBFILE on this subfile or before 
the next CLOSE or automatic close on the file. 
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*The CN Statement* 

The ON statement specifies what action is to be taken when 
an interruption results from the occurrence of the specified 
error condition. 

General Format: 

ON <ERR0REI1E (file-name) > <SYSTEM > ; 

<L ISTEE BOR > <GC TO lahcl> 

Syntax Rule: 

The ON statement must be a subaroument in a DB 

preprocessor function reference. 

General Rules: 

1. The CN statement determines how an error occurring 
for the specified condition is to be handled. 
Whether the error is handled in the standard DB 
fashion or by a user-supplied method is determined 
by the action specification in the ON statement, 
as follows: 

a. If the action specification is SYSTEM, the 

standard DB action is taken. For most 

conditions, the system simply posts the 
ONCCDE field and raises the ERROR condition. 
(Note that the standard DB action is always 
taken if an interruption occurs and no ON 
statement for the condition is in effect.) 

b. If the action specification is GO TO, the 
user has supplied his own error-handling 
action at label. Control is not transferred 
to label when the CN statement is executed; 
control is transferred only when an error 
results from the occurrence of the specified 
condition. 

2. The action specification established by executing 
an ON statement remains in effect unless it is 
over-ridden by the execution of another ON 
statement specifying an action for the same 
condition. 
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•The OPEN Statement* 

The OPEN statement opens a file by associating a file name 
with a DATA BASE. It may also specify attributes for the 
file . 

General Format: 

OPEN FILE (file-name) CHILE (expression) > <access> 

<function> 

<, FILE (file- name) CHILE (expression) > Caccess> 

Cf unction>>. . . ; 

where "access* 1 is: 

DIRECT ( SEQUENTIAL 

and "function* 1 is: 

INPUT | OUTPUT | UPDATE 

Syntax Buies: 

1. The OPEN statement must be a subargument in a DB 
preprocessor function reference. 

2. Several files can be opened by one OPEN 

statement. 

General Buies: 

1. If a file is not opened by an OPEN statement, it 
is automatically opened when a BEAD or LOCATE 
statement for the file is first executed, 

2. Opening an already opened file by an OPEN 

statement causes it to be closed and reopened, 

3. If the TITLE option is specified, the value of the 
expression is converted to a character string the 
first eight characters of which identify the data 
base to be associated with the file. If the TITLE 
option is not specified, the file-name is taken 
to identify the data base. 

4. If no access attribute is specified, DIBECT is the 
default unless a WFITE statement on the file is 
used in the same compilation, thus implying the 
SEQUENTIAL attribute. 

5. If a function attribute is specified, it 
determines the direction of data transmission 
permitted for the file. If no function attribute 
is specified, it is implied from the usage of 
other data base statements cn the same file in the 
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compilation (e.g., BEPUT implies UPDATE). If no 
other data base statements cn the same file appear 
in the compilation, the default is INPUT. The 
only oser permitted to access and OUTPUT or UPDATE 
file is the owner of that file. 
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*The PUT FIELD Statement* 

The PUT FIELD statement moves a data element value to the 
current record or subcecord of a file for subsequent 
transmission to the data base; it may cause the value to be 
validated and/or converted to an internal form and it may 
also cause a cross-reference to be automatically entered in 
an index file. 

General Formats 

POT FILE (file-name) FIELD (f ield-name<, field-oame> ...) 

FROM fexpressicnC, expressicn> ...); 


Syntax Euless 

1. The PUT FIELD statement must be a sufcargument in a 
DE preprocessor function reference. ‘The READ 
Statement* 

2. Several data element values can be moved by one 
PUT FIELD statement. In this case, a 
corresponding expression must be specified for 
each field-name. 

General Rules: 

1. The FILE clause specifies the data base file to 
which the data element value is to be subsequently 
transmitted. It must be an OUTPUT or UPDATE file 
owned by the user who executes the PUT statement. 
It may not be an associated file or an index 
file. 

2. A current exclusive record or subrecord (depending 
on the field-name) of the file or subfile must 
have been established when the PUT statement is 
executed. Several PUT statements may be executed 
on a current exclusive (sub) record of the file. 

3. The field-name is an expression that specifies the 
name of the data hase field into which the data 
element value is to be moved. The value of the 
expression is converted to a character strinq the 
first eiqht characters cf which identify the 
field. The field-name may not specify the key 
field of the record or any ether read only field. 
The PUT statement moves a value to a field element 
that had no previous value, 

a. If the field is not subdivided into elements, 
it must have had a null value before the POT 
statement is executed to give it a value. 



PAGE 65 


b. If the field is a multiple-element field, a 
new element will be added at the right end of 
the field. 

4. The expression in the ERCH clause specifies the 
data value to be given to the field element. The 
value of the expression is converted to a varving 
length character string, if necessary, validated 
and/or converted tc an internal form and moved 
into the current record of the file. (If the data 
base field element is variahle-lenqth , other 
fields are automatically shifted to make room.) 
The varying length character strino value after 
any conversion to an internal form must have a 
length greater than xerc; i.e,, a null string is 
an invalid data value for a POT statement. 

5. If the data base field has an inverted index file, 
a cross-reference of the internal data element 
value to the key of the (sub) record will be 
automatically entered in the inverted index 
file. 

6. The (sub) record with the new data element value 
will be transmitted to the data base when an 
UNLOCK statement for the (sub) file is executed or 
immediately before the next LOCATE or READ on the 
(sub) file or immediately before the next CLOSE or 
automatic close operation on the file. 
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*The POT LIST INTERNAL KEY FBCM Statement* 

The PUT LIST INTERNAL KEY FROM statement moves an internal 
key value to extend a list of keys in main storage. 

General Format: 

PUT LIST (list-pointer) INTERNAL KEY FROM (expression 

<, expressions , ,) ; 


Syntax Rules: 

1, The POT LIST INTERNAL KEY FFCN statement must be a 
subargument in a DB preprocessor function 
reference, 

2, Several internal key values can be moved by one 
POT LIST INTERNAL KFY FROM statement. 

General Rules: 

1, The list-pointer in the LIST clause specifies the 
user's pointer identifying the list of keys in 
main storage to which the internal key value is to 
be moved. It must have been set when the POT LIST 
INTERNAL KEY FROM statement is executed. In the 
case of a list pointer havinq a NOLL pointer 
value, a list error condition will be raised, 

2. The expression in the FRCM clause specifies the 
internal key value to be moved to the list. The 
value of the expression is converted to a varying 
length character string which must be the same 
length as the list element size. If the length is 
different or zero (null) an error condition will 
be raised. 
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•The READ Statement* 

The BEAD statement causes a parent record or a subrecord to 
be t ransmitted from the data base and established as the 
current record of the file (cr as the current subreccrd of 
a subfile); it may also cause transmission of the previously 
current record {or subrecord of a subfile) to the data 

base • 

♦Alien READing according to a XIST of subreccrd ID keys. 
General Format; 

READ FILE (file-name) <f i le-pcsiticninq> <WOLOCK>; 
where file-positioning may be: 

KEY (expression) f 

LIST (list-pointer) <KEY (rel-key) > ) 

PER SUBFILE (ctlfield) 

Syntax Buie; 

The READ statement must be a sufcarguroent in a DB 

preprocessor function reference. 

General Rules: 

1. The FILE clause specifies the data base file from 
which the record is to be transmitted. It may not 
be an OUTPUT file. 

2. If the file is net open, it will be opened 
automatically unless PER SUEFIIE is specified. 

3a. If no file positioning option is specified, the 
next sequential record , following the one 

previously read, will be transmitted. If the file 
is newly opened, the record having the lowest 
internal key value will be transmitted, 

b. If the KEY file-positioning option is specified, 

the value of the expression will be converted to a 
varying length character string, validated and/or 
converted to an internal form and used to 

determine which record will be transmitted. If 
the key cannot be found, a key error condition 
will be raised, but the record having the next 
lower internal key value will be transmitted. 

c. If the LIST f ile-positicning option is specified, 
the file may not be an index file. The 
list-pointer must be a pointer expression that 
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identifies a list of anchor or subrecord keys in 
main stcraqe to control the READing. It must have 
been set when the READ statement is executed. 
The keys in the file list identified oust be 
compatible with the internal anchor keys of the 
file, or with the subrecord keys of one of its 
subfiles. In the latter case the list determines 
which subfile will be accessed for a subrecord to 
be made current. In the case of a list-pointer 
having a NOLL pointer value, a key error condition 
will be raised and no record will be 
transmitted. 

If the LIST clause is not followed by a KEY 
clause, the internal READ cursor of the list will 
be incremented to indicate that the next element 
of the list, in order of ascending internal key 
values, will be used to determine which 
(sub)record will be transmitted. (If the internal 
BEAD cursor was reset, the element having the 
lowest internal key value will be used. If the 
internal READ cursor was cn the last element, the 
cursor will be reset, a key error condition will 
be raised, and no (sub) record will be 
transmitted. ) 

If the I 1ST clause is followed by a KEY clause, 
the value of the rel-key expression will be 
converted to a fixed binary integer of maximum 
precision. 

If rel-key has a value of xero, the internal BEAD 
cursor cf the list will be reset. No (sub) record 
will be transmitted and no error condition will be 
raised. 

If rel-key has a negative value, such as -1, the 
internal READ cursor of the list will be 
decremented to indicate that the previous element 
of the list, in crder of internal key values, will 
be used to determine which (sub) record will be 
transmitted. (If the internal READ cursor was 
reset, the element having the highest internal kev 
value will be used. If the internal BEAD cursor 
was on the first element the cursor will be reset, 
a key error condition will be raised, and no 
(sub)record will be transmitted.) 

If rel-key has a positive value the internal READ 
cursor of the list will be set to indicate that 
the element in the rel-key position of the list 
will be used to determine which (sub) record will 
be transmitted. (If rel-key is greater than the 
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number of keys in the list, the cursor will be 
reset, a key error condition will be raised, and 
no (sub)record will be transmitted.) 

d. If the PEP SUEFILE file-positioning option is 

specified, the parent record of a current 
subrecord will be transmitted. The value of the 
ctlfield expression will be converted to a 

character strinq the first eight characters of 
which identify the subfile control field. A 
current subrecord of the subfile must have been 
established by a PEAD SUBFILE statement when the 
REAL PEE SUEFILE statement is executed. The 
internal parent key field value on the subrecord 
will be used to determine which record will be 
transmitted. 

e. No KEYTO option is provided. A GIT FIELD 
statement, following a BEAD statement, may be 
used for this purpose. 

4. Any PEAD statement referring to an UPDATE file 

will cause the record to be locked for exclusive 
use unless the NCLOCK option is specified. A 
locked record cannot be PEAD by any other task 
until it is unlocked. Any attempt to HEAD a 
record locked by another task results in a wait. 
Subsequent unlocking is accomplished by the 
locking task through the execution of an UNLOCK, 
READ, LOCATE, CLOSE or implicit close operation on 
the file. 
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*Tha bead INDEX Statement* 

The READ INDEX statement causes an index record to be 
transmitted from the data base and established as the 
current record of the index. 

General Format: 

REID TILE (file-name) INDEX (indfield) <index-positioning>; 
there index-positicninq may be: 

KEY (expression) 

Syntax Rule: 

The BEAD INEIX statement must te a sutargument in a DB 

preprocessor function reference. 

General Buies: 

1. The FILE clause specifies the data tase file from 
which an index record is to be transmitted. It 
may not be an OUTPUT file. 

2. If the file is ret open, it will be opened 
automatically. 

3. The INEEX clause specifies the index file from 
which the index record is to be transmitted. The 
indfield expression value is converted to a 
character string, if necessary, the first eight 
characters of which identify the indexed field. 
If the user who executes the READ INDEX statement 
is not the owner of the file, the indfield may not 
specify a field that the owner has not authorized 
the user to GET. 

4a. If no index-positioning option is specified, the 
file must be an INPUT file. The next sequential 
index record, following the one previously read, 
will be transmitted. If the index file has not 
been previously read, the record having the lowest 
indexed field value will te transmitted. 

b. If the KEY index-ncsiticning option is specified, 
the file may be an INPUT or UPDATE file. The 
value of the expression will be converted to a 
varying length character string, if necessary, 
validated and/or converted to an internal index 
key form and used to determine which index record 
will be transmitted. If the key cannot be found, 
a key error will be raised, but the index record 
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having the next Icwer internal 
will he transmitted, 

c. No KEYTO option is provided, A 
statement, following a BEAE INDEX 
be used for this purpose. 

5, A BEAD INDEX statement never locks 
for exclusive use. 


index key value 

GET INDEX KEY 
statement, mav 

an index record 
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* The BEAD sdbfile statement* 

The READ SUBFILE statement causes a subrecord to be 
transmitted from the data base and established as the 
current sufcreccrd of the subfile. 

General Format: 

READ FILE (file-name) SUEFILE (ctlf ield) <subfile-positioning> 

<NOLOCK>; 


where subfile-positioning may be; 

KEY (expression) 

Syntax Rule: 

The READ SUEFILE statement must be a subargument in a 

DB preprocessor function reference. 

General Rules: 

1. The FILE clause specifies the data base file from 
which a subrecord will be transmitted. It may not 
be an OUTPUT file. 

2. If the file is net open, it will be opened 
automatically. 

3. The SUBFILE clause specifies the subfile from 
which the subreccrd is tc he transmitted. The 
ctlfield expression value is converted to a 
character string, if necessary, the first eight 
characters of which identify the subfile control 
field. If the user who executes the READ SUBFILE 
statement is net the owner of the file, the 
ctlfield may not specify a subfile that the owner 
has not authorized the user to READ. 

4. a If no subfile-positioning option is specified, the 

file must be an INPUT file. The next sequential 
subrecord following the one previously read, will 
be transmitted, if the subfile has not been 
previously read, the subreccrd having the lowest 
subrecord ID hey value will be transmitted. 

4.b If the KEY subf ile-positioninq option is 

specified, the file may be an INPUT or UPDATE 
file. The value of the expression will be 

converted to a varying length character string, 
if necessary, converted from numeric character to 
binary (24, 7) internal subrecord kev form and 

used to determine which subrecord will be 
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transmitted. If the sutrecord key cannot be 
found, a key error condition sill be raised, but 
the subrecord having the next lower internal 
subrecord key value will be transmitted, 

4.c No LIST subfile-positioning option is provided for 
the BEAD SUBFILE statement; the regular BEAD with 
LIST file-positioning may be used for this purpose 
because the list determines if and which subfile 
is to be accessed. 

h.d No subfile-positioning option is provided for 
reading the reqion of sutrecords dependent on the 
current rcot record; GET SUEFILE IIST SET followed 
by BEAD LIST statements are very flexible for this 
purpose. 

4. e No KEYTO option is provided. A GET FIELD 

statement, following a BEAD statement, may be 
used for this purpose. 

5. A BEAD SUBFILE statement referring to an UPDATE 

file will cause the sutrecord to be locked for 
exclusive use unless the NC1CCK option is 

specified. A locked sutrecord cannot be BEAD by 
any other task until it is unlocked. Any attempt 
to BEAD a subrecord locked by another task results 
in a wait. Subsequent unlcckinq is accomplished 
by the lockinq task through the execution of an 
UNLOCK SUBFILE, BEAD SOBFIIE, Or LOCATE SUBFILE 
operation on the subfile or a CLOSE or implicit 
close operation on the file. 
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•The REPOT Statement* 

The REPUT statement replaces a data element in the current 
record or subrecord of an UPDATE file for subsequent 
retransmission to the data base; it mav cause the value to 
be validated and/cr converted to an internal form and it may 
also cause a cross-reference to be automatically deleted and 
another entered in an index file. The BEPUT statement may 
be used to delete a whole record or subrecord and all 
cross-references to it in index files. 

General Format; 

BEPUT FILE (file-name) FIELD f field-nameC, field-name> 

FROM (expression^ exrression> ...); 

Syntax Rules; 

1. The REPUT statement must be a subarqument in a DB 
preprocessor function reference. 

2. Several data element values can be replaced by one 
REPUT statement. In this case, a corresponding 
expression must be specified for each 
field-name. 

General Rules: 

1. The FILE clause specifies the data base file to 
which the data element value is to be subsequently 
retransmitted. It must te an UPDATE file owned by 
the user who executes the REPUT statement* It may 
not be an associated file or an index file. 

2* A current exclusive record cf the file must have 
been established when the BEPUT statement is 
executed* Several REPUT statements may be 
executed on a current exclusive record of the 
file. 

3. The field-name is an expression that specifies the 

name of the data base field whose data element 
value is to be replaced. The value of the 

expression is converted to a character string the 
first eight characters of which identify the 

field. 

a. If the field is the key field of an anchor record, 
the expression in the FROM clause must have a null 
value (zero lenqth) and the whole root record and 

all of its dependent subrecords in all subfiles of 

the FILE will be deleted. 
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b. If the field is the kev field of a subrecord, both 

the subrecord and its parent record roust be 

current. The expression in the PROP! clause must 
have a null value (zero length) and the whole 
subrecord will be deleted, 

c. Otherwise the field-name may not specify a 

read-only field. 

If the field is not subdivided into elements, its 
value will be replaced. If the field is a 
multiple-element field, the element taken by the 
last GET of the FIEID since the current 
(sub) record of the file was READ will have its 
value replaced. If no element was fpimd fpr tje 
GET FIELD or if no GET cf the FIELD of the 
current (sub) record of the file was executed, an 
error condition is raised. 

4, The expression in the FFOM clause specifies the 

new data value to be ctiven to the field element. 

The value of the expression is converted to a 

varying length character string, validated and/or 
converted to an internal form and moved into the 
current (sub) record of the file. (If the data 
base field element is variafcle-lenqtb and the new 
value’s length is different from the old, other 
field elements are automatically shifted as 
necessary. ) 

5a, If the data base field is the key field of the 
anchor record and the expression in the FFOM 
clause has a null value, all cross-references to 
the key of the parent reccrd and its dependent 
suhrecords will be automatically deleted from all 
index files for the file specified in the FILE 
clause. 

b. If the data base field is the ID key field of a 
subrecord and the expression in the FROM clause 
has a null value, all cross-references to the ID 
key of the subrecord will be automatically deleted 
from all index files for the subfile. 

c. If the data base field has an index file, the 
cross reference of the old internal data element 
value will be automaticallv deleted, and a 
cross-reference of the new internal data element 
value to the key of the record will be 
automatically entered in the index file. 

6. The (sub) record with the new data element value 
will be retransmitted to the data base when an 
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UNLOCK statement, for the (sub) file is executed or 
immediately before the next LOCATE or BEAD on the 
(sub) file or immediately before the next CLOSE or 
automatic close operation on the file. 
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’The SET LIST LIKE LIST Statement' 

The SET LIST IIKE LIST statement dynamically allocates main 
storage for a new list to later contain an estimated number 
of keys, copies the key field name and conversion routine 
name etc., from an existinq list, and sets a pointer 
identifying the new list. 

General Format: 

SET LIST (new-list-pointer) SIZE (dimension) LIKE LIST 

(list-pointer) ; 

Syntax Rule: 

The SET LIST LIKE LIST statement must be a subargument 

in a DB preprocessor function reference. 

General Rules: 

1. The list-pointer in the IIKE LIST clause must be a 
pointer expression that identifies a list of keys 
in main storage tc be referenced for prefix 
information such as key element length etc* In 
the exceptional case of a list pointer having a 
HULL pointer value, a NOLL pointer value will be 
returned. 

2. The SIZE clause specifies an estimate of the 

number of keys that will subsequently be put into 
the new list. For example, it could be the #LIST 
count of the existing list or a multiple of it. 
The dimension expression value will be converted, 
if necessary, to a fixed binary integer of maximum 
precision and used to govern the allocation of the 
first segment of the new list. 

3. The new-list-pointer in the SET LIST clause 

specifies the user’s pointer identifying the new 
list of keys in main storage. It must be the 
identifier of a pointer variable declared by the 
user. Regardless of its former value, it will be 

set to identify the new list of keys in main 

storage. The new list remains allocated in main 
storage until the user executes a FREE LIST 
statement. 
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*The ULIST function* 

ULIST builds a copy of a list of keys omitting duplicated 
key values and returns a pointer value identifying the new 
list to the point of invocation. If The given list has only 
unique key values, ULIST returns the given list pointer 
without copying the list. 

Befe rnece: 

ULIST (list- pointer) 

A ULIST function reference is used as or in an expression; 
it is not to be a subargument in a EE preprocessor function 
reference. The user nay not declare any attributes for the 
ULIST function; the following statement will be generated 
auto matically : 

EECLABE ULIST ENTBY (POINT EB) BETUBUS (POINTER) ; 

Argu ment: 

The list-pointer argument must be a pointer expression that 
identifies a list of keys in main storage. It must have 
been set when the ULIST function is invoked. 

Result: 

The value returned by the ULIST function is a pointer 
identifying the new list having only unique key values. 
However, if the argument list is found to not have any 
duplicated key values, its list pointer is simply returned 
(this always happens when the arqument list is null or has 
only one key) . 
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*The UNLOCK Statement* 

The UNLOCK statement makes a locked current record or 
subrecord available to other tasks for BEAD operations: it 
may cause transmission of the current record or subrecord to 
the data base. 

General Format: 

UNLOCK FILE (file-name) <SUBFIL1 (ctlf ield) >; 

Syntax Buie: 

The UNLOCK statement must be a subargument in a DB 

preprocessor function reference. 

General Buies: 

1. The FILE clause specifies the data base file whose 
current record is to be unlocked. The file must 
have the UPDATE attribute. 

2. A record can be unlocked only by the task which 
locked it. 

3a. If no SUBFILE clause is present, the current root 
record will be unlocked. 

3b. A SUBFILE clause, if present, specifies that the 
current subrecord of a subfile is to be unlocked. 
The ctlfield expression value is converted to a 
character string the first eiqht characters of 
which identify the control field. 

4. If the locked current (sub) record has been updated 
by a PUT or REPUT FIELD statement, the UNLOCK 
statement will cause it to be retransmitted to the 
data base. It continues to be the current 
(sub) record of the file, but PUT and BEPUT 
statements are invalid until another current 
(sub) record is established. 

5. Unlockinq a (sub) record that was BEAD with the 
NOLOCK option or that has already been UNLOCKed 
has no effect. 
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'The OPLIST Function' 

Unique Parent LIST builds a list of the unique parent (root) 
record keys from a given sub-record (children) kev list and 
returns a pointer value identifying the new list to the 
point of invocation. The new list has the same number of 
parent keys as the number cf sufcrecord keys in the qiven 
list. Parent keys will not he repeated, even if more than 
one of the given subrecord keys are dependent on a 
particular parent record. A previously current and updated 
sukrecord of the subfile referenced by the qiven list will 
be transmitted to the data base. The subrecord identified 
by the last key in the given list will remain as the current 
subrecord of that sub-file; any current root or index 
records or subreccrds of other subfiles will remain current. 
The BEAD cursor of the given list will be reset. 

Beference: 

OPLIST (file-name, child -list-pointer) ; 

An OPLIST function reference is used as or in an expression; 
it is not to be a subargument in a EE preprocessor function 
reference. The user may not declare any attributes for the 
UPIIST function; the following statement will be generated 
auto mat ically; 

DECLARE OPLIST ENTRY ( , P T R ) RETOBNS (FTP); 

Arguments; 

The file-name argument specifies the data base file from 
which sufcrecords are to be transmitted. It may not be an 
OUTPOT file. If the file is not open, it will be opened 
automatically. The file-name must be used in at least one 
DBEL/I statement elsewhere in the proqram. 

The child-list-pointer argument must be a pointer expression 
that identifies a list in main storage of subrecord keys 
from the data base accessed by file-name. It must have been 
set when the OPLIST function is invoked. 

Result; 

The value returned by the OPLIST function is a pointer 
identifying the new unigue parent list. The new list will 
be in order of ascending internal parent key values without 
duplicated values. If the given subrecord list is null, a 
NOIL pointer value will be returned. 
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• The WRITE Statement* 

The WHITE statement causes a physical record (presumably, 
from a backup file) to be transmitted to a SEQUENTIAL OUTPUT 
file. 

General Format: 

WRITE FILE (file-name) FROM (variable) ; 

Syntax Buie: 

The WBITE statement must be a subarqument in a DB 

preprocessor function reference. 

General Buies: 

1. The FILE clause specifies the file to which the 
record is to be transmitted. It must be a 
SEQUENTIAL OUTPUT file owned fcv the user who 
executes the WBITE statement. 

2. If the file is not open, it is opened 

automatically with the SEQUENTIAL OUTPUT 

attributes. 

3. The variable in the FBOH clause, declared and 
filled by the user, contains the record to be 
written. It must have the self-defining format of 
an internal variable-length record. Its key field 
value (without validation or conversion) must be 
higher, in order of ascending internal values, 
than that of the record transmitted by the 
previous WRITE statement for the file. (The 
record does not become the current record of the 
file for purposes of PUT statements.) 
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'The #XREF Function* 

#XREF calculates the number cf cross reference keys in the 
current record of an index and returns it to the point of 
invocation. 

Reference: 

IXREF (file-name, indfield) 

A #X REF function reference is used as or in an expression; 
it is not to be a subarqument in a DB preprocessor function 
reference. The user mav not declare any attributes for the 
#XRE F function; the following statement will be generated 
automatically: 

DECLARE iXREF ENTRY (,CHAB (8) ) RETURNS (FIXED BIN (31)); 
Ar gu ments; 

The file-name identifies a data base file. It may not be an 
OUTPUT file. 

The indfield specifies the index file. A current index 
record must have been established by a READ INDEX statement 
when the #XREE function is invoked. The indfield expression 
value is converted to a character string, if necessary, the 
first eight characters of which identify the indexed 
field. 

Result; 

The value returned by the #XREF function is a binary integer 
of maximum precision qivinq the number of cross-references 
in a current index record. If an index record is not 
current, a zero value will be returned. 
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APPENDIX A. 


FILE LEVEL STATEMENT'S 


ON E BRORFILE (fflfcb) \ SYSTEM I 

|_GO TO latel_l ; 


OPEN FILE (mfcb) <TITLE (*mfct»)> 1 DIRECT 1 | INPUT 1 

| SEQUENTIAL j ! OUTPUT 

» UPDATE | 


CLOSE FILE (rafcb) <ERASE>: 


RECORD LEVEL STATEEE NTS 


LOCATE FILE (mfcb) f KEYFFOW <GXpr) \ 

| _ SUEFIL E (scfn)_| ; 


BEAD FILE (ofcfc) | forwards | <NOLOCK>; 

1 KEY (expr) 1 

| LIST <ptr) <KEY fn) > \ 
t_PEF SUBFILE (scfn) _ | 


BEAD FILE (fflfcb) SUBFILE (scfr) | forwards ) <NOLOCK>; 

1_KEY (expr)_| 


READ FILE (ffifcb) INDEX (ifn) | forwards | ; 

|_KEY fexpr)_| 


UNLOCK FILE (rafcb) <SUBFILE (scfn)>; 


PHYSICAL BECCBD STATEMENTS 



GIT PILE (mfcb) BECORD INTO (var); 

UBITE FILE (mfcb) FROM (var); 

FIELD LEVEL STATEMENTS 

POT FILE (mfcb) FIEID (f n<, f n2>) FBOH (expr<,expr2>) ; 
GET FIXE (mfcb) FIELD (fn<,fn2>) INTO ( var<, var2>) ; 

GET FILE (mfcb) INDEX {ifn) KEY INTO (var); 

BEPtJT FILE (mfcb) FIELD (fn<,fn2>) FFCK (expr< ,expr2>) 
full word = #FIELD (mfcb, f n) ; 
fullword = #XBEF (mfcb, ifn) ; 

DATABASE LIST STATEMENTS 

GET FILE (mfcb) |~SUEFILE (scfn) ~ ] LIST SET (ptr) ; 

| INDEX (ifn) ! 

(^anchor is index _\ 

GET FILE (mfcb) <SDBFILE (scfn)> KEY SET (ptr) ; 

Ptr - CCLIST (mfcb, scfn, ptrl); 

Ptr - CPLIST (mfcb, ptrl); 

Ptr = UPLIST (mfcfc, ptrl); 

NCN-DATAB ASI LIST STATEMENTS 
ON LISTEBROR | “"SYSTEM “) 



t_GO TO labels | ; 

GET LIST (ptr) KEY (0) ; 

GET LIST (ptr) KEY < (n) > INTO (var) : 

GET LIST (ptr 1) KEY SET (ptr2>; 

Ptr = ULIST (ptr 1 ) ; 

Ptr = DUPLIST (ptr 1) : 

Ptr = LIST (ptr 1»cp f ptr2) ; 

SET LIST (ptr2) SIZE (dim) LIKE LIST (ptrl) 
GET LIST fptrl) INTERNAL KEY INTO (var); 

PUT LIST (ptr2) INTERNAL KEY FRCB (expr) ; 
Full word = #LIST (ptr); 

FREE LIST (ptr C,ptr2>); 


FREE LIST 
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dim 

expr 

fn 

ifn 


®f cb 
n 

op 

ptr 

scfo 

var 


GLOSSAB? 

an expression resulting in a numerical 

dimension value 

an expression resulting in a value 

an expression resulting in a field name 

an expression resulting in an indexed field 
name 

mainline FILE control blocK name 

an expression resulting in a numerical 

subscript value 

list operator; • |* or *8* or 

pointer to a list of teys in main stroage 

an expression resulting in a subfile control 
field name 

variable data area name 
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TOEIC C.4 - DBJOIN - JOINING NEW USEES 


I. INTRODUCTION 

The JOIN command gives the NASIS Data Base 
Administrator the ability to control the access of 
retrieval users to the various files of the system. In 
addition, it also allows the DEA to specify passwords, 
time slice values and authority codes which influence 
use of the system. The information is maintained in 
data set NASIS, USEBIDS. 

II. COMMANDS: 

JOIN 

The JOIN command establishes a new NASIS-ID which can 
be used to access the system. This is accomplished by 
creating a new record in the data set and inserting the 
values for the various data fields. 

Command: JOIN 

Operands: NASISID=id , PASS NO E Decode, TS- value, 

AUT aut hor it y, TILES = file list 


Where: 

id 

identifies the new NASIS-ID to be created. 

Specified as: a 1-8 character alphanumeric value 
beginning with a letter. 

code 

identifies the password or indentif icaticn code to 
be used for this NASIS-ID. 

Specified as: a 1-8 character alphanumeric 

value. 

Default: No password will be assigned. 

value 

indicates the magnitude of the time slice in Milli 
Seconds to fee assigned tc this NASIS-ID under MTT 
mode of operation. 

Specified as: a 1-5 digit numeric value, 

authority 

indicates the authority level to be assigned to 
this NASIS-ID under HIT mode of operation. 



PAGE 90 


Specified as: a cne character code, *0* for user 

or * E * for DEA, 

Default: , n» will be assigned* 

file list 

identifies the files to be made available to this 
NASIS-ID. 

Specified as: a list of fully qualified file 

names, i«e. DBA-ID. FILE-ID. 


QUIT: 

The QUIT command removes a NASIS-IE from the list of 
valid ids. 

Command: QUIT 

Operand: NASISlE=id 


CHANGE: 

The CHANGE command is used to alter the values of one 
or more of the data fields (ether than the file list) 
associated with a particular NASTS-ID. 

Command: CHANGE 

Operands: NASISlD=id , P AS SEC FD=code,TS= value, 

AUTH=authcrity 


ADD: 

The ADD command is used to specify new files which are 
to be added to the list of files to which a given 
NASIS-ID is permitted access. 

Command: ADD 

Operands: NASISTD=id ,FILES-f ile list 


DELETE: 

The DELETE command is used tc remove files from the 
list of files to which a particular NASIS-ID is 
permitted access. 
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Command: DELETE 

Operands: NASISIE=id, FILES-file list 


DISPLAY: 


The DISPLAY command is used to list the files available 
to a particular NASIS-ID, alcnq with the other data 
values present in his identification record. 

Command: DISPLAY 
Operand: NASISID=id 


III. EXAMPLE 


OSEE: 

SYSTEM: 

USEE: 

SYSTEM: 

DSEP: 

SYSTEM: 

USES: 

SYSTEM: 


join john, ace, 99999 , , 

JOHN JOINED TC NASIS PITH PASSWORD* ACE, 
TIMfSLICE=99999 MILXESF CONES , AND AUTHOPITY=. 
add john, (safety .asrdi, safety. erf s) 

Adds the two files to the list of files 
available to JOHN, 
display john 

Display the current information maintanined 
for JOHN. 

change john,auth=d 

Applies the appropriate change. 
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TO EC C D.2 - DESCRIPTOR EDITOR 


I. INTRODUCTION 

The Descriptor Editor is an editing proqram used for 
creating and updating the field descriptors of a NASIS 
Data Base. 

II. INVOKING THE EDITOR 

The Descriptor Editor is invoiced bv entering the EDIT 
command and specifying the appropriate mode of 
operation and the descriptor file to be edited. 

EDIT HODE=<CREATE| UPDATE |RESTORE>,EILE=filename 


Where: 

BODE 

Is Specified as: 

CREATE: assumes that no data files exist and that 
the user is either creating or continuing to 
create field descriptors. 

UPDATE: assumes that data files do exist ana that 
the user wishes to modify the description of 
one or more of the fields* The UPDATE mode 
allows the user to make changes that do not 
affect the physical format of the record, 

RESTORE; reads in previously, check-pointed 
descriptors and continues processing in the 
CREATE mode. 


FILE 

Is specified as the name of the data base 
descriptors the user wishes to edit. Specified as 
an alphanumeric strinq of at most 6 characters, 
the first of which must be alphabetic. 

For all inodes the first letter of the mode type is a 
sufficient abbreviation. If the entered mode value is 
invalid, the editor will re-prompt the user for a 
correct value. If the user defaults the prompt for the 
mode, the Editor will terminate and control will be 
returned to the HTT director. 

EXAMPLES: 

1. The user wants to create a new data base 
whose name is FECPIE. 
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SYSTEM: 

SYSTEM: 

USER: 

SYSTEM: 

USEB: 

SYSTEM: 

USEB: 


ENTER BASIS COMMAND: 
ENTER: 

EDIT 

ENTER MODE: 

CREATE 

ENTER FILE NAME: 
PEOPLE 


2. The user wants to modify the descriptors for 
an existing data base whose name is PGMS, 


SYSTEM: INTER NASIS COWHAND; 

SYSTEM: ENTER: 

USER: EDIT UPDATE, PGMS 

3. The user has a checkpointed set of 
descriptors for the data base GAMES which he 
wishes to continne defining. 


SYSTEM: ENTER NASIS COMMAND: 

SYSTEM: ENTER: 

USER: EDIT RESTORE, GAMES 


III. DEFINITIONS 

The following definitions are used throughout this 
section : 

1. Boolean Values - Used where ever a yes or no type 

of response is required. The following are 

acceptable values fcr a *yes* type of response: 

YES, Y, TRUE, T, ON, 1. 

The following are acceptable values for a 'no* 
type of response: 

NO, N, FALSE, F, OFF, 0. 

2. Fieldname - Is a character string of 1-8 

characters lono of the following form: the first 

character must be alphabetic, and the other 
characters, if any, must be alphanumeric. 

3. Routine Name - Is a character string of 1-8 

characters long with the following form: the 

first character must be alphabetic, and the rest 
of the characters, if any, must be alphanumeric. 


IV. THE CREATE MCDE COMMANDS 

A. The ADD and CHANGE COMMANDS allow the user to 
create a new field descriptor or modify existing 
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field descriptors. 

ADD (fCHANGE) FLDNAME=f ield-naroe, 

TYPE= (?LDTYPE=field-type 

<, AIIGN=<B3GHT|l,EFT») , 

FORM- (FLDFOBW= fie Id -format, 
FLDI£N=fieia-lenqth, 

E LE K LE N=ele men t- length, 
ElEMLIM=€l€ment-n ember 
<,UNIQUE-<Y| N>>) , 

BOUTIN ES= (CGNV=convers ion -routine, 

FORMAT® format ting-routine, 
?ALIE=v a li da t ion-routine, 
YAIIDAEG=validation-argument) , 
INDEXED® (INDEX=<Y |N>, 

IFID NA ME=f ield-name 
<,EXTINT=<INTEBNAI|EXTEBNAL>, 
IXTIFN=external-lenqtb, 

SPANNE D=< Y 1 N>>) , 

ASSOCED- ( ASSOC-<Y |N>, 

AFIDNA MI- field -name) , 
SUEFIIIC=(SUBFILI=<Y|N>, 

SFlDNAME=f ield-name) , 

SUEFIELD® (SUBFID=<Y | N> , EASEFLD® field-name, 
OFFSET=cf f set 

<, <FILE =<* filename ) A NCHOS>> 
or <FIIE=<ASSCCIATED|5UBFILE>, 
IIENAME2=field-name») 


Where: 

FLBNAHE 

identifies the field to be added. 

Specified as: a valid fieldname. 

F1DTYPE (FIEID TYPE) 

identifies the physical format of the 

field. 

Specified as: 

A - alphanumeric character string 

B - bit string 

BN - 8 bit unsigned binary number 

BP - packed bit string. These fields 
will be placed immediately after 
the kev field as one continuous bit 
string. 
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HX - hexadecimal 

LN - larqe numberic (32 bit siqned 
binary number). 

S - scientific (14 digit decimal number 
within the range of 10**-75 : 

10**+75) . 

SD - scaled decimal (nine digit numbers 
within the range 1G**-9 : 

10***9) . 

SN - short numeric (16 bit signed binary 
number) ♦ 

SS - short scientific (six digit 
decimal number within the absolute 
range of 1G**-75 : 10**+75), 

ALIGN (ALIGNMENT) 

identifies riqht or left alignment of the 
field. 

Specified as: ’FIGHT* or *F» for right 

alignment and ’LEFT* or *L* for left 

alignment. 

FLDFOBM - (FIELD FOE MAT) 

identifies the logical format of the field. 

Specified as: F-FIXED, V-VAHIABLE, FE-FIXED 

ELEMENT, VE-VAFIABXE ELEMENT. 

FLDLEN (FIELD LENGTH) 

indicates the length of fixed fields or the 
maximum length for ether types of fields. 

Specified as: a positive number. 

(1) For the file key field, the maximum 

field length is 256. 

(2) For all other fields: 

(a) If FLDFOFM=F, then the maximum 
field length is 3996 minus the key 
field length; 

(b) Fcr all ether values of FLDFOHM , 
the maximum lenqth is 3994 minus 
the key field lenqth. 
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E1EMXEN {ELEMENT LENGTH) 

indicates the maximum lenqth of fixed and 
variable elements. 

Specified as: a positive number with the 
range of 1-256 if FIDFCRM is FE: the range is 
1-255 if FLDFOFM is Vi. 

ELEHLIM 

indicates the maximum number of elements 
allowed in the field. 

Specified as: a positive number. 

(1) If FLDFCRM=FE f then the maximum number 
of elements is equal to the field 
length. 

(2) If FLDFOFM^VE, then the maximum number 
of elements is the field length divided 
by two. 

UNIQUE 

indicates whether or not all element values 
within a multi-element field are to be 
unigue. 

Specified as: a boolean value. 

Default: N 

CONV {CONVERSION ROUTINE NAME) 

identifies the name cf the routine used to 
convert the input data as it is placed into 
the data base. 

Specified as: a routine name. 

FORMAT {FORMATTING FCUTINE NAME) 

identifies the routine used to format the 

data for output from the data base. 

Specified as: a routine name. 

VALID {VALIDATION ROUTINE NAME) 

identifies the name of the routine used to 
validate the input data. 

Specified as: a routine name. 

VALIDARG {VALIDATION ROUTINE ARGUMENT) 

indicates the argument required bv the 
validation routine to validate the input 
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values. 

Specified as: a hexadecimal character string 

of 1-100 characters. 


INDEX 

indicates whether the field is to be 

indexed. 

Specified as: a boolean value. 

Default: N 

IFLDNAME 

identifies a net her field previously defined 
with which this field is to be indexed. 

Specified as: a valid fieldname of a 

previously entered indexed field. 

Default: the Editor assumes that this field 

is the first entered field of a new index 
file. 

EXTINT 

indicates whether the hey of the index file 
is to be in internal or external form. If 
the key values are to be in external form, 
then the field values must be formatted 
before being placed on the index file. 

Specified as: INTERNA! or I for internal 
form or EXTERNA! or E for external form. 

Default: internal form, i.e., the value used 

on the index file is the same as that stored 
in the anchor file. 

EXTLEN (EXTERNA! 1ENGTH) 

indicates the maximum length possible for an 
formatted value of the external field. 

Specified as: a positive numeric value in 

the range 1-256. 

NOTE: if the EXTINT entered value is 

external, then EXTIEN must be specified. 

SPANNED 

indicates that this index is to consist of 
spanned records. 

Specified as: a boolean value. 
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Default: N 

NOTE: this implies that the maximum lenqth 

for index beys can be no larqer than 255 to 
allow for a one byte spanned counter. 

ASSOC (ASSOCIATED) 

indicates whether the field is to be 
associated . 

Specified as: a boolean value. 

Default: t) 

A FIONA HE 

identifies another field previously defined 
with which this field is to be associated. 

Specified as: a valid previously entered 

field name. 

Default: the Editor assumes that this field 

is the first entered field of a new 
associated file. 

SUBFILE 

indicates whether the field is tc appear on a 
subfile. 

Specified as: a boolean value. 

Default: N 

SFLDNAME 

identifies another field previously defined 
which identifies the subfile on which the 
field is to be placed. The field named may 
be the subfile control field. 

Specified as: a valid previouslv defined 

fieldname. 

SOB FID 

Indicates whether this field is to be defined 
on either a part or the whole of another 
field. 

BASEFLD 

identifies the field on which this new field 
is to be defined. 

Specified as: a valid previously defined 

fieldname. 
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OFFSET 

indicates the tit or character position of 
the defined field on which this subfield is 
to start. 

Specified as: a positive numeric value 
between zero and the lenght of the defined 
field minus one. 

NOTE: the offset value must be specified if 
the subfield is specified. 


FILE 

identifies the descriptor region on which 
resides the field that is the defininq base 
for this subfield. 

Specified as: 

(1) The character **• concatenated to the 
descriptor file region name, 

(2) The anchor file which may be entered as 

either of the follcwinq: ANCHOR or 

AN. 

(3) An associated file which may be entered 

as either of the following: ASSOCIATED 

or AS. 

(4) A subfile which may be entered as either 

of the following: SUBFILE or S. 

Default: will be assumed to be the anchor 

file. 

NOTE: this parameter only needs to be 

entered if the defined fieldname is not 
unique within the data base, such as 

RECLEN. 

FLDNAME2 

identifies a field which is used to determine 
which associated file or which subfile is 
being referenced. 

Specified as: a valid fieldname. 

NOTE: Any parameter to the CHANGE function 

which is defaulted, will imply that the 
existing value for that descriptor field will 
be left unaltered. 
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NOTE: There is a user default variable 
"EDPBOMPT" which when set equal to "Y" will 
cause the user to be prompted for every 
possible applicable parameter while the user 
is either ADDinq a new field or CHANGing an 
existing field. In the normal mode there are 
parameters such as field alignment ("ALIGN”) 
which are not prompted for if the user does 
not enter them in the command stream. 


EXAMPLES: 

1, When first creating a new set of descriptors, 
the user is first prompted for the anchor 
file key field. 


SYSTEM; 

USER: 

SYSTEM: 

USER: 

SYSTEM: 

USEF: 

SYSTEM: 

OSIB: 

SYSTEM: 

USEF: 

SYSTEM: 


ENTER FEY; 

ALL ACCESSNO 
ENTER FIELDTYPE; 

A 

ENTER FIE ID FORMAT: 

F 

ENTER FIELD LENGTH: 

8 

ENTER ROUTINES: 

(return - wants standard defaults) 
ENTER: (prompt for next editing 

request) 


NOTE: If the user declines to enter the key 
field information, the Editor is terminated 
and control is returned to the Maintenance 
director. 


2. The user wishes to add the field USEFNAME 
which is to be a varyinq element field, each 
element is tc be 12 characters long and allow 
for 50 elements per record. USERNAME is to 
be placed cn the associated file along with 
OSERTYPE. It is also to be inverted. 


SYSTEM: 

ENTER: 

USER: 

ADD 

SYSTEM: 

ENTER 

USEF: 

USERNA 

SYSTEM: 

ENTER 

USER: 

A 

SYSTEM: 

ENTER 

USER: 

VE 

SYSTEM: 

ENTER 

USER: 

500 

SYSTEM: 

ENTER 

USER: 

12 


FIELD NAME: 

ME 

FIELD TYPE: 
FIELD ICFMAT: 
FIELD LENGTH: 
ELEMENT LENGTH: 
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SYSTEM: ENTER NUMBER OF E1EHENTS : 

USER: 50 

SYSTEM: ENTER ROUTINES: 

USER: (CONV=UNCYT,FCRM AT=UNFMT, 

VALIE = D NVA1 , ) 

SYSTEM: IS FIFIE TO EE INDEXED? 

USER: YES 

SYSTEM: CN WHICH INDEX FILE IS FIELD TO BE 

PLACED? 

USER: (return) 

SYSTEM: IS FIEID TO BE ON AN ASSOCIATED 

. FILE? 

US EH t Y 

SYSTEM: ON WHICH ASSOCIATED FIIE IS FIELD TO 

EE PLACED? 

USER: USERTYPE 

SYSTEM: IS FIILE TO EE PLACED ON A SUBFILE? 

USER: NO 

SYSTEM: ENTER DEFINING BASE FIELD NAME: 

USER; (return) 

SYSTEM: ENTER: 

3. The user wishes to change the field length on 

field SOCSECNC from 8 to 9 and wishes to 

make the index on which it appears a spanned 
index. 

SYSTEM: ENTER; 

USER: CHANGE SOCSECNC, , ( ,9) ,Y) , ,, , 

B. The ADELINE Descriptor Function 

This function allows the user to create a 

descriptor with all the same specifications as a 

previously defined field. 

ADELINE FLENAMF 1=new- fieldname, 

ELENA ME2=other -fieldname 

where: 

FLDNAME1 

identifies the new descriptor to be added. 
Specified as: a valid fieldname. 

FLENAME2 

identifies a previously defined field of 
which the new field is to be an exact 
duplicate except for the field name. 


Specified as: 


a valid field name 
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EXAMPLE: 

1. The user wishes to add field MIBKEYRB to have 
exactly the sa ire specifications as the field 
HAJKEYWD. 

SYSTEM: ENTER: 

OSES: ADDLIKE MIKKE YWD , MAJKEY^D 

The CHECKPOINT Command 

Checkpoint allows the user to save the descriptors 
currently defined in a separate TSS YAM file. 

CHKFOINT (none) 

CHFPOINT should be used when it is deemed 
necessary to save the descriptors as rapidly 
as possible. The user may continue to 
process at a future time VIA the Restore 
Command. 

The CHEATESOE Command 

The command allows the user to create a subfile. 

CREATSUB FL DN A ME 15 con tic 1- fie ld-name , 

M A X8 EC 5=#- records , 

ASSOC=<Y l N> , 

AFIDNA ME=f ield-name 


Hhere : 


FLDNAME 

identifies the field to be known as the 
subfile control field. 


Specified 

as: 

a valid field name. 



HAXRECS 


- 




indicates 

the 

maximum number 

of 

subfile 

records that 

can occur per 

anchor 

file 

record. 






Specified 
of 1:1325. 

as: 

a binary number 

in 

the 

range 


ASSOC 

indicates whether the field is to be 
associated. 

Specified as: a boolean value. 
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Default: N 

AFLE8AME 

identifies another field, previously defined, 
with which this field is to be associated. 

Specified as: a valid previously entered 

fieldname. 

EXAMPLE: 

The user wants to create a subfile for w PETS n 
which is to be associated with CHILD. 

SYSTEM: ENTEB: 

USES: CBEATSUE PETS, 20, Y, CHILD 

E. The DELETE Command 

This command allows the user to delete a 
previously created field descriptor other than 
the key field. 

DELETE FLDNAME= fieldname 


Where: 

FLDNAWE 

identifies the field tc be deleted. 

Specified as: previously described field 

name, 

F. THE DISPLAY COMMAND 

This command allows the user to display the 
specif icaticns entered for a previously created 
descriptor. 

DISPLAY FLDNAME=f ieldname 


Where: 

FLDNAME 

identifies the field descriptor to be 
displayed. 

Specified as: a valid fieldname. 

G. The END command 

This command terminates a descriptor editor 
session. 



PAGE 104 


END (none) 

After the END command has finished, control will 
be returned to the Maintenance director. If the 
user has not Fill’d since making additions, 
deletions, or modifications, he will be queried as 
to whether he wishes to FILE the descriptors. If 
the user wishes to terminate, then the descriptor 
editor will indeed terminate the current session; 
otherwise, the user will be prompted for his next 
descriptor editor command. 

B, The FIELDS Command 

This command allows the user to display the names 
of all the field descriptors thus far defined, 

FIELDS (none) 

I, The FILE Command 

This function allows the user to indicate that he 
wants the descriptors to be written from virtual 
memory to disk stcraqe. 

FILE DESC0R=<F|N> 


Uhere : 

DESCOK 

indicates whether or not the descriptors are 
complete. If a NO value is indicated no data 
can be loaded into this file. 

Specified as: a boolean value. 

Default: N 

J. The FLDSEC (Field Security) Command 

This command permits the data base owner to 
restrict access to a field or a group of fields. 

FLDSEC FLDNftME= (field-name) , 

SEC UHITY= (<<flDE | DELETE >. > 

secur itY-code<, . . »>) 


ihere: 

FLDNSM E 

is a list of one or more existing fieldnames 
to which the data base owner wishes to 
restrict access. 
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Specifies as; a list of valid fieldnames. 
SECURITY 

is a list of security codes appended by an 
add-delete code separated from the security 
code by a period. The add-delete code is 
specified as ft or ADD for adding a security 
code and t) or DELETE for deleting a security 
code. If no add-delete code is entered, it 
is assumed the user is adding the security 
code. The security code is specified as an 
alphanumeric character string of 1 to 8 
characters. A maximum of 18 security codes 
may be specified for any field. 

EXAMPLE: 

The data base owner wishes to restrict the 
fields ACCOUNT and VAIUE to the persons with 
the security codes BOB, HflFFY, and JOHN and 
to delete TOM from the security list. 

SYSTEM: ENTER : 

USER: FLESEC (ACCOUNT , V ALDE) , (ADD . BOB , 

A • HARR Y , A. JOHN, D. TOM) 


The MOVE Command 

This command allows the user to reposition fields 
within the defined data layout. 

MOVE FLDNAMEl=new -location- fieldname, 
FLDNAME2=f ieldname 


where: 

ELD NAM El 

identifies which field or the new location 
after which the field specified by FLDNAME2 
is to be positioned. 

Specified as: a valid fieldname. 

ELDNAME2 

identifies the field tc be moved. 

Specified as: a valid fieldname, 

NOTE: A redefined field, i.e., subfield, 

cannot be moved as its position is determined 
by the position of the base field. If a 
subfield is specified as the new position 
fieldname, the MOVE command will locate and 
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use the base field name as the new position 
field name* 

NOTE: A superfield cannot be used as a new 

position fieldname, nor can it be moved, as 
a superfield consisting only of other fields 
has no field position* 

EXAMPLE: 

The user has entered the three fixed fields 
in the following: AREACOEE, LOCALNUM, 

EXCHNG The user wishes to change the order to 
AREACODE, EXCHNG, ICCAXNUM. 

SYSTEM: ENTER: 

USER: MOVE AREACODE, EXCHNG 

Notice this could also be accomplished by the 
following: 

SYSTEM: ENTER: 

OSER: MOVE EXCHNG, LOCAL NOM 

The PRINT Command 

This command generates a printer listing of all 
the field descriptors and file descriptors as they 
exist in core at the time the PRINT was issued. 

PRINT (none) 

The RENAME Command 

This command permits the user to change the name 
of a field without altering any of its other 
specifications or its location in the data 
record. 

RENAME ELDNAMEl=new-f ieldname, 

FLENAME 2= old-fieldname 


Where: 

FLDNABE1 

identifies the new field name. 
Specified as: a valid fieldname, 

FLDNAME2 

identifies the existing field name 
Specified as: a valid fieldname. 



PAGE 107 


EXAMPLE: The user wishes to change the name of the 
field OLDNAHE to the name NEWNAME. 

SYSTEM: ENTER: 

USER: RENAME NBRNA ME , OIDNA ME 

N. The RECSEC (Record Security) Command 

This command permits the user to control access to 
a group or groups cf records within the data 
base. 

RECSEC D F LD N A MI= field -name, 

SECUFIT Y= (<<ADD|DEIETE>.> 

security-code: mask<, . . .>) 

Where: 

DFLENAM E 

is the existing fieldname to which the file 
record security is to apply. 

Specified as: a valid fieldname. 

SECURITY 

is a list of up to 18 security codes and 
security masks determining who is to be 
permitted access to the secured records on 
the file. It is specified as an add-delete 
code followed by a period, followed by the 
security code, followed by a colon, followed 
by the security mask. The add-delete code is 
specified as ADD or A for adding a security 
code, or DELETE or D for deleting a security 
code. The security code is an alphanumeric 
character strirg of 1-8 characters. The mask 
is two digit hexadecimal code. 

The security cede is used to compare against 
the value in the record security field of a 
record to determine whether cr not a user has 
access to that record. 

O. The RESTORE Command 

This command permits the user to restore tc core 
memory the descriptors which had been previously 
saved by the use of the CHKECINT command. 

RESTORE (none) 

P. The SAVSTRT (Save Strategv) Command 
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This command allows saving of descriptor editor 
commands in the strategy data set for future 
recreation of descriptors as they existed in 
virtual memory when the SAVSTRAT command was 
issued. 

SAVSTRT STFTNAFE^strat egy-name 


Where: 

STFTFAME 

is the strategy name in the strategy data set 
in which the descriptor editor commands are 
to fce saved. 

Specified as: a 1-16 character long 

alphanumeric character string. 

The Superfld {Define Superfield) Command 

This command allows the user to create a new field 
descriptor which is defined as consisting of Data 
from several fields. 

SUPEFFLE ELBU AHE=f ieldname , 

ROOTINES=FCRH AT= formatting-routine, 
FLDLIST= (<<INTEFNAH EXTEENAt>. > 
f .ield-nameC, . . .>) 


Where: 

FLDHAME 

identifies the name of the new superfield. 
Specified as: a valid field name. 

FORMAT 

identifies the routine used to format the 
data for output from the data base. 

Specified as: a routine name. 

FLDLIST 

is a list cf the previously defined 

fieldnames from which this superfield is to 
be composed. The order of the fieldnames 
used to define the superfield is the order in 
which they were entered. The user may 

specify whether the internal or external form 
of the field is tc be passed to the 
superfield formatting routine. 

Specified as: a list of up to 16 character 
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strings of the form: The output format 
concatenated tc a period concatenated to the 
fieldname to be included in the superfield. 
The format type internal may be specified 
as: 


INTERNA! or I 

The format type external may be specified 
as: 

EXTERNAL or E 

Default: If the output format is omitted, 
then it will he assumed to be the external 
format type, 

NOTE: The superfield components must stay within 

the following restrictions: 

1, It may contain at most one multi-element 
field. 

2. It may contain components from one but not 
more than one subfile. 

THE UPDATE RODE COMMANDS 

A. The CHANGE COMMAND 

This command allows the user to modify a 
previously defined field. 

CHANGE FLDNAME=f ieldname, 

TYPE= (FLDTSPE= field -type 

<,ALIGN=<RIGHT |LEFT») , 

FORM= {FLDFQFM^f ield-f ormat , 

FLDLEN=f ield-lsngth, 
ELE8!EN=element-length , 

EL EMI IM=element -number 
< r UNIOUE=<Y! N>>) , 

FCUTINE= (CCNV=con vers ion-routine, 

FOFRAT^f or matting -routine, 

VALID= validation-routine, 

VA LID A RG= validation -argument) 


flhere: 

FLDNAME 

identifies the field tc be modified. 
Specified as: a valid fieldname. 
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FLDTYPE 

identifies the physical format of the 
field. 

Specified as: 

A for an alphanumeric character string, of 
which each character may consist of any 
valid EBCtIC character. 

B for a bit. string. 

BN for an 8 bit unsigned binary number 
which has a value in the range 0-255, 

BP for a packed bit string the same as B, 
except that these fields will be placed 
immediately after the key field as one 
continuous bit strino. 

HX for a strinq of hexadecimal numbers. 

IN for numeric or a 32 bit signed binary 
number. 

S for scientific cr 14 digit decimal 
number within the range of 10**-75 : 

1G***75. 

SD for scaled decimal nine digit number 
within the range of lQ**-9 : 10**+9. 

SN for numeric or 16 bit signed binary 
number. 

SS for short scientific or a six digit 
decimal number within the range of 
1 0**-75 ; 10**+75. 

ALIGN 

identifies either right or left alignment of 
the field. 

Specified as: SIGHT or R for right alignment 

and LEFT or I for left alignment. 

FLDFOSM 

identifies the logical format of the field. 

Specified as: F for FIXED, V for VARIABLE, FE, 
for FIXED ELEMENT, VE , for V ASIA ELE ELEMENT. 


FLDLEN 
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indicates the length cf fixed fields or the 
maximum length for ether types of fields* 

Specified as: a positive integer. 

(1) For the anchor file key field, the 
maximum field length is 256. 

(2) For all ether fields: 

(a) If FLDFORH=F, then the maximum 
field length is 3996 minus the key 
field length; otherwise, 

(b) For all other values of FLDFQBH, 
the maximum length is 3994 minus 
the key field length. This allows 
for a two fcyte field length 
indicator. 

ELEH1EN 

indicates the length of fixed elements or the 
maximum length for variable elements. 

Specified as: a positive numeric value with 

the range of 1-256 if FLDF08H is FE, else the 
range is 1-255 if FLEIC8P! is ve. This allows 
one byte for an element length indicator. 

ELEHLIH 

indicates the maximum number of elements 
allowed in the field. 


Specified as: a positive integer. 


(1) 

If 

FLEFC RH=FE, then the 

maximum 

number 

of 

elements is eoual 

to the 

field 


length. 



(2) 

If 

?LDFOPK=VE, then the 

maximum 

number 

of 

elements is the field 

length 

divided 


by 

two. 




UNIQUE 

indicates whether or not all element values 
within a multi-element are to be unique. 

Specified as: a boolean value. 


CON V 

identifies the name of the routine used to 
convert the input data as it is placed into 
the data base. 
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Specified as: a routine name. 

EOHMAT 

identifies the routine used to format the 
data for output from the data base. 

Specified as: a routine name. 

VALID 

identifies the name cf the routine used to 
validate the input data. 

Specified as; a routine name. 

VALIDASG 

indicates the argument required bv the 
validation routine tc validate the input 
values. 

Specified as: a hexadecimal character strinq 

of 1-100 characters. 

MOTE; In the UPDATE mode, values to the CHANGE 
function will net te accepted which cause changes 
to be made to other field descriptor records, such 
as chanqing the field length if the field format 
is fixed as this changes the base length of the 
data records. 

NOTE: Any parameter to the CHANGE function which 

is defaulted, will implv that the existing value 
for that descriptor field will be left 
unaltered. 

Note: There is a user dafault veriable "EDPBOMPT" 
which when set equal to "Y" will cause the user to 
be prompted for every possible applicable 

parameter while the user is CHANGE* inq an existing 
field. In the normal mode there are parameters 
such as field alignment ("ALIGN") which are not 
prompted for if the user dees not enter them in 
the command stream. 

EXAMPLE: 

The user wishes to change the specifications 
for the field PEOPLE to EIGHT alignment, 
change the element length from 20 to 30 and 
the element limit from 5 to 10. 

SYSTEM: ENTEB: 

USEE: CHANGE PECE1E ,(, EIGHT ),(, ,30 , 1 0) , , 
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B. The DISPLAY COMMAND 

This command allows the user to display the 
specifications entered for a previously created 
descriptor. 

DISPLAY ELD NAME- fieldname 


She re: 

FLDNAME 

identifies the field descriptor to be 
displayed. 

Specified as: a valid fieldname. 

C. The END COMPAND 

The END command is terminates a descriptor editor 
session 

END (none) 

After the END command has finished, control will 
he returned to the Maintenance Director. 

D. The FIELDS Command: displays all of the descriptor 
fieldnames in the descriptor file record, and all 
of the descriptor fieldnames in a field 
descriptor. 

FIELDS (none) 

E. FLDSEC (Field Security) Command: permits the file 

owner to restrict access to a field. 

FLDSEC FLBN A ME= field -name, 

SECURITY= («ADD f DEIETE>. > 

securitv-ccdeC, . , .>) 


FLDNAME 

is an existing field name to which the owner 
wishes to restrict access. 

Specified as: a valid fieldname. 

SECURITY 

is a list cf security codes appended by an 
add-delete code separated from the security 
code by a period. The add-delete code is 
specified as A or ADD for adding a security 
code and D or DELETE for deleting a security 
code. If no add-delete code is entered, it 
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is assumed the user is adding the security 
code. The security code is specified as an 
alphanumeric character string of 1 to 8 
characters. A maximum of 18 security codes 
may be specified for any field. 

The PATCH Command 

This command is used to change the value of almost 
any descriptor field on any descriptor record in 
any descriptor region. Tc use the PATCH command, 
the user must dc a REVIEW of the desired 
descriptor record. This not only displays the 
contents of this descriptor but also positions to 
the record that is to be patched. 

PATCH {keyword^ text <,,,.>) 


Where: 

keyword 

identifies the descriptor field that is to be 
patched. 

text 

is the value with which the descriptor field 
specified in ’keyword' is to be patched. 

The user may specify any number of patches in a 
parenthesised list. 

The following is a list of file descriptor or 
header descriptor field names that may be patched 
and their values. 


HEADER FIELDNAME FIELD VALOIS 


(1) 

FILITYPE 

ANCHOR or 1, ASSOCIATE 

or 2, 



SDBFIIE or 3, INDEX 

or 

4. 

(2) 

DESCRCT 

A 

positive integer 


4000. 

(3) 

BSELNGTH 

A 

positive integer 

<= 

4000, 

(4) 

DESCOK 

A 

boolean value. 



(5) 

SPANNED 

A 

boolean value. 



(6) 

DATA 

A 

boolean value. 



(7) 

MNTNABLE 

A 

boolean value. 



(8) 

MNTNING 

A 

boolean value* 



<9> 

LOADABLE 

A 

boolean value. 



<10) 

RECSECFP 

A 

positive integer 

<= 

261. 

(ID 

RSECTYCD 

The fctm of the patch 

text is: 


(n) security-code:mask 


Where: 
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n 

is the index of the security code to be 
patched. She index Bust be entered or the 
patch will be rejected. 

Specified as: a positive integer <= 18. 

NOTE: The next security code value may be 

added to the list by specifying the next 
larger index value. 

Refer to the RECSEC command writeup for a 
discussion of the security parameter. 

EXAMPLE: 

The user wishes to patch the anchor header 
descriptor sc that BSELNGTH=3 1 , DATA=NO, and 
the second value of record security to 
BOB: 60 . 

SYSTEM: ENTER 

USER: REVIEN * ' , *SEADER 

SYSTEM: (displays the anchor header 

information. ) 

SYSTEM: ENTER: 

USIF: PATCH (BSELNGTH=3 1 , DATA=N , 

R SECTYCD= (21 ECE:60) 

SYSTEM: ENTER 

The following is a list of field descriptor 
fieldnames that may be patched along with their 
values. 

FIELD DESCRIPTOR 

FIE1BNAMES IXELE VALDES 


(1) ASSCCFIL a one character string in the 

range *0* to *9*. 

(2) SOEFILE a one character string in the 

range * Q * to * Z * . 

(3) INVEILE a one character string in the 

ranae *A* to *P*. 

(4) READONLY a boolean value. 

(5) SUECNTBL a boolean value. 

(6) VAPFLD VARYING or V, FIXED or F. 

(7) BITELD 


a boolean value 
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(8) 

NUKALIGN 

RIGHT or R , LEFT or L. 


(9) 

VARELT 

VARYING or V, FIXED or 

F. 

(10) 

UNIQOELT 

a 

boolean value. 


(11) 

INBEXEXT 

EXTERNAL or B r INTERNAL 

or 

(12) 

GENERCRT 

a 

routine name. 


(13) 

VALIDBTN 

a 

routine name. 


(14) 

REFORMAT 

a 

routine name. 


(15) 

FLEFOSIT 

a 

positive integer <= 

4000 

(16) 

FLDLEN 

a 

positive integer. 

If 


field is indexed then the 
maximum value is 256. 
Otherwise the maximum value is 
4000. 

(17) ELTLIN a positive integer. If the 

elements are fixed length, the 
maximum value is 4000. 
Otherwise the maximum value is 
2000 . 

(18) ELTLEN a positive integer <= 256. 

(19) VAIIDARG a hexadecimal character string 

of length 1 to 100 
characters . 

(20) NAMEFLD The patch text is of the 

fori: 

(n) « INTERNAL) EXTERNAL>. > fieldname 
Where: 


is the index of the 
superfield component to 
be patched. 

Specified as: a positive 
integer <- 16. 

NOTE: The index must be 
entered or the patch will 
fce rejected. 
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Refer to the StJPEPFLD 
command writeuo for the 
superf ield components 

description. 

(21) SECURITY The natch is in the form: 

(n) security-code 

where: 

n 

is the index of the 
security code to he 
patched . 

Specified as: a positive 

integer <= 18. 

NCTE: The index must be 

entered or the patch will 
be rejected. 

security-code 

is an alphanumeric 

character string of 
length 1 to 8 

characters. 

EXAMPLE: 

The user wishes to patch the field PHONENUM 
on associate file 1 to have a formatting 
routine of PHONFMT on the third component of 
this superfield to be in external form and 
have the field name of 10CALNUM. 

SYSTEM: ENTER: 

USER: REVIEW 1 , PHCNENUM 

SYSTEM: (displays the field information.) 

SYSTEM: ENTER: 

USER: PATCH (REFCRKAT=PHCNFMT , 

NAM EFLE= ( 3) E. LOCALNUM) 

SYSTEM: ENTER: 

G. The RECSEC (RECORD SECURITY) COMMAND 

This command permits the owner to control access 
to a grcup or qrcups of records. 

RECSEC CFLDN A HE= field-name, 

SECURITY= («AIE | DELETE>.> 

security-code<,. . . >) 
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Where: 

DFLDNAME 

is an existing fieldname which is used to 
define which file record security is to 
apply. 

Specified as: a valid fieldname. 

SECURITY 

is a list of up tc 18 security codes and 
security masks determining who is to be 
permitted access to the file. It is 
specified as an add-delete code, followed by 
a period, followed by the security code, 
followed by a colon, followed by the security 
mask. The add-delete code is specified as 
ADD or A for adding a security code, or 
DELETE or D for deletinq a security code. 
The security code is an alphanumeric 
character string of 1-8 characters. The mask 
is a two digit hexadecimal code. 

The security cede is used to compare against 
the value in the record security field of a 
record to determine whether cr not a user has 
access to that record. 

NOTE: In the UPDATE mode the record security must 

already exist for the file to be able to use 
EEC SEC . In the UPDATE mode, BECSEC is used to 

update the existinq list of record security codes 
and masks. 

The BE VIEW COWHAND 

This command is used to review the contents of any 
descriptor record cn any descriptor file. This 
includes dummy records, file descriptor records 
and those records such as REC1EN which are not 
unique to the entire data base* 

REVIEW FILE=f ile-name, 

FLDNAME=<*HEADIB1 f ield-name> 


Where: 


identifies the descriptor region containing 
the fieldname to be reviewed. 

Specified as: the full descriptor region 

name or the character suffix of the 


FILE 
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descriptor region. 

NOTE: A null value is taken to indicate the 

anchor region. 

FIDNANE 

identifies the field which is to be 
reviewed. 

Specified as: a valid fieldname or either of 

the following character strings: *HEADEF or 

* which will imply a review of the file 
descriptor for the descriptor region named 
above. 
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APPENDIX A. 

A. Descriptor Editor command format, 

1, Edit Descriptor. 

EDIT BODE = <CREBTE (UPDATE) RESTOBE> 

B, Create Rode command formats, 

1. ADD FI ENABE= field- name, 

T YFE= (FLDTYPE 3 field -type 

< ,ALIGN=<FIGHT | IEFT>) , 
FOBK=(FLDFCFB=field-format, 

FLDLEN= field-length, 

ELEBLEN=element- length, 

ELERLIB=ele men t- number 
<,UNIQ0E=<Y |N») , 

SOUTINES 3 (CON Y=c on version-routine, 

FOfiKAT= formatting- routine, 

YAIID- validation -routine, 
VBIIEABG= valid at ion-aroumentl , 
INDEXED 3 (INDEX=<YJ N>, 

IFLENAHE 3 field- name 
<,EXTINT=<INTFSNAL|EXTEFNAL>, 
EXTIEN=external-lenqth, 
SPANNEE=<Y|N») , 

ASSOCED 3 (A5S0C 3 <Y1 N>, 

AFLENABF 3 field-name) , 

SUEFILED 3 (S0BFILE=<Y| N>, 

SFLDNABE-field-narae) , 

SUBFIBLD 3 (SDBF1D=<Y J N> ,BASEFID=FIELDNAHE, 
OFF S ET=of fset 

<,<FIlE=<*f ilename) ANCHOB» 
or <FIIE=<ASSOCIATFD1 SUBFIIE>, 
FIDNA BE2 3 field-natne>>) 

2. ADDLIKE FLDNABE=new fieldname, 

FLDMNE2=other-£ieldname 

3. CHANGE FIDNA BE=field-na me, 

TYPE- (FLDTY PE 3 field -type 

<, ALIGN=BIGHT|LEFT») , 

FOBS 3 (FIDFORP = f ield -forma t , 

FLDLEN= field-length, 

ELE M IE N=el erne nt- length, 
ELEHIIR=element-number 
< , UNIQUE 3 <Y| N>>) , 

FCUTINES 3 (CONV=conversion-routine, 

FOPMAT=f or mat tin a- routine, 
VALIE 3 validaticn- routine, 
VALIDAPG=validation-argument) , 
INDEXED 3 (INDEX=<Y|N>, 
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IFL£NAHF= field-name 
<,EYTINT=<I STERNAL) EXTERNAL^ 
£XTLEN=external-lenqt h, 
SFANN£D=<Y| N>>) f 
ASSOCID= (ASSCC=<Yf N>, 

A FLDNAHE= field-name) , 
SUEFILED=(SOEFILE=<Y| N>, 

S FI DN A HE=f ield-name) , 

SUBFIELD= (B A SEFLD=f ield-name , 

SUBFIELD= (S0EFLD=<7IN>,EASEFLD=FIELDNAME 
CFFSET=offset 

<,<FILE=<* filename) ANCHOR » 
or <FILE=< ASSOCIATED J SUEFILE> , 
FLDNAHE2=field-name») 


4. CHKPCINT (none) 


5, CREATSUE ELDNAME~control-f ield-name , 
HAXRECS=#-records, 

A SSOC=< Y ) N> * 

A FLN AM E= field-name 


6. DELETE FLDN A HE=f ield-name 

7. DISPLAY ELDNAME= field-name 
0. END (none) 

9. FIELDS (none) 

10. FILE DESCOK=<Y1n> 

11. FLDSEC FIDNAHE= (field-name<,. . .» , 

SEC08ITY= («ADD1DELETE>.> 

secnrity-code<, » » •>) 

12. HOVE FLENAHE1=new-lccation-f ield-name, 

FLENAME2=f ield-name 


13. PRINT (none) 


14, RECSEC DFLDNAME=f ield-name. 
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SECURITY 3 (<< ADD j DEIETEV. > 

security-code: mask<,...>) 


15. RENAME FIINAME 1=new-f ield-name, 
FLDNAME2 3 old-f ieldna me 


16. RESTORE (none) 


17. SAVSTRT STRTNAME-strateqy-name 


18. SDPEFFLE FLDNAME=f ield-name , 

ROUTINES- (CONY-con vers ion- routine, 

FORMAT 3 forma ttinq -routine, 

7 AT ID 3 valid at ion- rout ine, 
YALIDARG 3 valida tion-arqument) , 
FLEt 1ST 3 (<<INTEENA1 | EXTERNA1>. > 
f ield-nameC,. ♦ .>) 

UPDATE MODE Command Formats. 


1. CHANGE FLDNAHE 3 f ield-naroe , 

TYPE 3 (FLETYPE 3 field-type 

<,AIIGN=<RIGHT|1EFT») , 

FORM 3 (FLEFCRM 3 field -for mat, 
FLDLEN-field-lenqth , 
ELEMLEN=eletnent-lenqt h, 

EL EMIIM^element-n umber, 

< , 0NIQUE=<Y) n>>) , 

ROUTINES 3 ( CO NV=con vers ion -routine, 

FOPMAT=f orma ttinq-routine, 
?ALID 3 validaticn-routine, 

VA l ID A BG= valida tion-arqument) 


2. DISPLAY FLDNAME=f ield- name 

3. END (none) 

4. FIELDS (none) 

5. FLDSEC FIDNAME 3 field-name, 

SECURITY 3 (<<ACD|DELETE>.> 

security-codec, . . . >) 



PATCH (f ield-naire=value 


PECS EC 


BEVIES 


EFIENAME=field-ijanie r 
SECURITY* (<< ADD j DEIETE>* > 

security -code :ib as k<. 


FIIE=file-’nan€ f 
f LDNAHE=<*HEADER|FIIID-Tia!ne> 
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APPENDIX B. 

CREATE HOEE 
OPERAND REIATICNSHIPS 

When creating descriptors there are certain implied 
relationships between the various operand combinations that 
may be specified. In those cases, the Descriptor Editor 
assumes the implied value and over-rides any value specified 
by the user. When modifying descriptors the Descriptor 
Editor normally interprets a default response to indicate no 
change to a particular operand. 

The following table indicates the default values and the 
maximum values for several parameters of the ADD command. 



TABLE 1 


tUT 


• CREATE MODE 

OPERAND DEFAULT AND MAXIMUM VALUES 


FLDTYFE 

fldfmt 

DEFAULT 

ALIGNMENT 

MAXIMUM 

FLDLEN 

MAXIMUM 

ELEMLEN 

MAXIMUM 

ELEMLIM 

A 

.. F 

L 

3996-Key Length 

NA 

NA . 

A 

V 

L 

39 9 4 -Key Length 

NA 

NA 

A 

FE 

L 

3994-Key Length 

256 

(FLDLEN) 

A 

VE 

L 

3994-Key Length 

255 

(FLDLEN/2) 

B 

F 

L 

1 

NA 

NA 

BN 

. F 

R 

1 

NA 

NA 

BN 

FE 

" ' R 

• 3994-Key Length • 

-■ * - i : 

' ■*•••--. - -(FLDLEN)- - 

BP 

F 

L 

1 

NA 

NA 

HX 

F 

L 

2 (3996-Key Length) 

NA 

NA 

HX 

V 

L 

2 (3994-Key Length) 

• NA 

NA 

HX 

FE 

L 

2 (3994-Key Length) 

255 

(FLDLEN) 

HX 

VE 

L 

2 (3994-Key Length) 

255 • 

(FLDLEN/2) 

LN 

F 

R 

4 

NA 

NA 

LN 

FE 

R 

3994-Key Length 

4 

(FLDLEN/ 4) 

s • t -‘. 

F 

■ - R 

8 .. .. •• - 

, . NA 

. NA 

S 

FE 

R 

3994-Key Length 

8 

(FLDLEN/ 8) 

SD 

F 

R 

5 

NA ■ 

NA 

SD 

FE 

R 

3994-Key Length 

5 

(FLDLEN/ 5) 

SN 

F 

R 

2 

NA 

NA 

SN 

FE 

R 

3994-Key Length 

2 

(FLDLEN/2) 

SS 

F 

R 

4 

NA 

NA 

SS . 

FE 

R 

3994-Key Length 

4 . 

(FLDLEN/4) 

/ ■ - - 


• . 

v*-. 

i . -» - 

•wii - *; • *. ...... * ^ ■ * - 



... . . ; •: .. ■■ 

* • 1 ;* - •; ’ " ' / - : . 

* - • - ~ •. i - 



(1). Default conversion, and formatting routine names are 
inserted. by the editor unless specified by "the user. 
The routine names have the format DBXXXYY, where; . 


n XXX” is either CVT for conversion routine or FMT 
for a formatting routine, and 

"YY" is "SP" for field type "A" and is the field 
type itself for all other field types. 
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APPENDIX C. 

PREDEFINED FIELDS 

In most cases when the user defines or creates a new 

fieldname there is coly one field descriptor created. There 
are, however, some exceptions to this which are enumerated 
below, 

Whoi the anchor file key field is completely defined by the 
user, the following fields are automatically defined and 
added to the list of field descriptors. 

1. The FILEKEY field is a field defined over the anchor 

file key field. This field has all of the 

characteristics of the anchor file key field except for 
the field name and that it is a readonly field, that is 
a redefined field. 

2. The fields FREFFOPH and COMMENTS are defined for the 
retrieval system COMMENTS is a varying length field 
designed to held any comment the user may wish to place 
there. FREEFOEM will allow the user to specify his own 
particular keywords for the file he is referencing and 
he is able to base strategies on these user entered 
keywords. 

The SECLEN is a predefine field which will appear in each 
descriptor region of the data base. This field defines the 
record length field which appears on each variable lenqth 
record in a file. 

When the user specifies record security for any file, for 
the first time, a field is created describino the record 
security code that appears in each data record of that file. 
This field is placed immediately after the anchor key for 
the anchor and associated files, and immediately after the 
parent key field on subfiles. 

The record security fieldname is created in the following 
manner for the different file types; 

1. ANCHOR file - the fieldname is RECSFC. 

2. ASSOCIATED file - the fieldname is FECSFC concatenated 
to the suffix of the associated file, i.e. 1 to 9. 

3. SUBFILE - the fieldname is the subfile control 
fieldname concatenated tc PS, 

When the user creates a subfile by the CPEATSUB command the 
following fields are defined; 
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1* The subfile control field itself which resides either 
on the anchor file or an associated file. 

2. The subfile key field which is the subfile control 
field name concatenated to ID, 

3. The subfile parent key field which is a copy of the 
parent anchor key field. This fieldname is created by 
taking the subfile control fieldname concatenated with 
PK. 

4. Allowance is made for subfile record security by 
creating the fieldname of subfile control field name 
concatenated to FS. 

The field characteristics cf each of the predefined fields 
are included in Table 2. 

All of the aforementioned fieldnames are included in a 
reserved list. These fields cannot be altered by the user 
except in the following manner: 

To modify FILEKEY, the anchor file key field must be 
modified* The predefined fieldnames for record 
security cannot be modified in any way and can only be 
created through use of the EECSEC command. The RECLEN 
field descriptor cannot be modified. The subfile 
control field and subfile key field cannot be modified 
once created. The subfile parent key field will only 
be changed to reflect changes in the anchor file key 
field. The fieldname fcr subfile record security can 
only be created through use of the FECSEC command. 

Table 3 contains the names of the reserved fieldnames. 
As subfiles are created, the subfile control fieldname, 
the subfile key fieldname, the subfile parent key field 
name, and the subfile record security fieldname are 
placed in the reserved fieldname table, which then 
become reserved field names subject to the above listed 
restrictions. 



TABLE 2 


M 


PREDEFINED FIELD CHARACTERISTICS 


FLDNAME 

COMMENTS 

FILEKEY 

FREEFORM 

RECLEN 

record^ 

security 

subiile^^ 

control 

subfile^ 15 

id 

subfile^"* 

parent 

ASSOCFIL 

1 

(none) 

1 

(none) 

(none) 

(5) 

(none) • 

(none) 

SUBFILE -• 

(none) 

(none) ; 

(none) ■ 

(none)- 

- (none) 

(none) 

(none) "" 

(hone) 

INVFILE .- 

(none) . . 

(none) . 

A 

(none) 

(none) 

(none) 

(none) 

(none) 

READONLY' 

NO 

Y 

NO 

YES 

NO 

YES 

NO 

YES 

SDBCNTSL 

NO 

N 

NO 

NO 

NO 

YES 

NO 

NO 

VARFLD 

VARYING 

F 

VARYING 

FIXED 

FIXED 

VARYING 

FIXED 

FIXED 

BITFLD 

NO 

N 

NO 

NO 

NO 

. NO 

no . . 

NO 

NUMALIGN 

LEFT 

(2) 

LEFT ' 

RIGHT 

LEFT 

RIGHT 

RIGHT . 

VARELT- — 

■ (none)' 

(none) 

FIXED 

(none) 

(none) 

FIXED 

(none) 

(none) 

UNIQUELT 

NO 

(none) 

NO 

(none) 

(none) 

YES 

(none) 

(none) 

INDEXEXT 

(none) 

(none) 

INTERNAL 

(none) 

(none) 

(none) 

(none). 

(none) 

GENERCRT. 

DBCVTSB 

(2) 

DBCVTSB 

DBCVTRL 

DBCVTHX - 

DBCVTID 

DBCVTID 

(2) 

VALIDRTN 

(none) 

(2) 

(none) 

(none) 

(none) 

(none) 

(none) 

(2) 

REFORMAT 

DBFMTSB 

(2) 

DBFMTSB 

DBFMTRL 

DBFMTHX 

DBFMTID 

DBFMTID 

(2) 

FLDPOSIT 

2 

4 

1 

0 

(4) 

(4) 

4 

7 

FLDLEN 

3988 

(2) 

3988 

4 

1 

(6) 

■ 3 

(2) 

ELTLIM- ■ 

- 0 

0 

.100 

0 

0 

(6) 

0 ■ 

0 

ELTLEN 

0 

0 

40 

0 

0 

3 

0 

0 

VALIDARG 

(none) 

(2) 

(none) 

(none) 

(none) 

(none) 

(none) . 

(2) 

NAMEFLD 

(none). . 

(none) _ 

(none) . 

(none) 

(none). . 

(none). 

(none)) 

(none) 

SECURITY 

(none) 1 * (3) 4 5 6 

(non e) UJ 

(none) UJ 

(none)^ 

(noner^ 

(none)r _ 

(none)\ \ 

. (non e)r_J. 




* f: ■*,. 

- ■ .■ — -7 .. 



. — r-- .. • 



(1) Refer ..tq. the text for the. derivation of , the .actual f ieldname^.^ ^ '■ 

c : ; -'^2) ^Th|- Actual ^aiue ib "taken from tlfT anchor jfcejf field. 7..",’.’. T. -W- ... •- 

* - "(3) There is 'no "field security,on these fields unless specified by the 

user through, use. of the FLOS EC command. - • - • • 

(4) The. value will be determined at -"FILE" time. : 

(5) -The value will depend on the "ASSOC" and "AFLBNAME"- parameter values 
• to the -GREAT SUB co mm a n d . 

(6) The actual value will depend on the input value to "MAXRECS" parameter 
to the CREATSUB command. 
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APPENDIX D. 

DESCRIPTOR f ID E OVERVIEW 

Each descriptor file is an indexed sequential (ISAM) region 
Data Set where the key is developed hy concatenating an 
eight character field name to a seven character file name. 
The name of the descriptor file is constructed by appending 
a "S" to the six-character data base name {padded with 
if necessary) * 

The first record of each set of descriptors is called a 
header record and has a field name of blanks. This record 
is used by the system tc reflect the current status and 
level of activity of that file, as well as controlling 
access to it, and is composed of fields described in Table 
4. The remaining records are the field descriptors, 
then selves, and are composed of the fields described in 
Table 5. 



TABLE 3 


PREDEFINED RESERVED FIELDNAMES 


1. COMMENTS 

2. FILEKEY 

3. FREEWORD 

4. RECLEN 

5. RECSEC 

6. RECSEC1 

7. RECSEC2 

8. RECSEC3 

9. RECSEC4 

10. RECSEC 5 

11. RECSEC6 

12. RECSEC7 

13. RECSEC8 

14. RECSEC9 



TABLE 4 


/3I 


FILE DESCRIPTOR FIELD SPECIFICATION 


field name 

FIELD 

TYPE 

FIELD 

FORMAT 

FIELD 

LOCATION 

FIELD 

LENGTH 

ELEMENT 

LENGTH 

ELEMENT 

COUNT 

RECLEN 

LN 

F 

0 

4 

0 

0 

KEY-.-. 

A ■ 

F 

4 

15 

0 

0 

FLENAME 

A 

F 

4 

7 

0 

0 

DATAPLEX 

A 

F 

; 4 

6 

0 

0 

SUFFIX 

A 

F 

10 

1 

0 

0 

FLDNAME 

A 

F 

11 

8 

0 

0 

FILETYPE 

A 

F 

19 

1 

0 

0 

DESCRCT 

SN 

F 

20 

2 

0 

0 

BSELNGTH 

SN 

F 

22 

2 

0 

0 

DESCOK 

B 

F 

24 

0(1) 

0 

0 

SPANNED 

B 

F 

24 

2(1) 

0 

0 

DATA 

B 

F 

24 

4(1) 

0 

0 

MNTNABLE 

. B 

F 

24 

6(1) 

o 

0 

MNTNING 

B 

F 

25 

0(1) 

0 

0 

LOADABLE 

B 

F 

25 

4(1) 

0 

0 

REMAINS 

HX 

F * 

26 

4 

0 

0 

RECSECFP 

SN 

F 

30 

2 

0 

0 

RSECTYCD 

A 

FE 

1(2) 

164 

9 

18 

(1) For 
the 

bit switches the length field is used to indicate 
bit location within the byte. 


(2) For variable length fields 
.as a variable field index.,. 

the location 

field is 

used 




TABLE 5 


field descriptor field specification 


/ 3 /<> 


FIELD NAME 

RECLEN 

..KEY. 

' FLENAME 
DATAPLEX 
SUFFIX 
FLDNAME 
ASSOCFIL 
SUBFILE 
INVFILE 
. READONLY 
SUBCNTRL 
VARFLD 
BITFLD 
NUMALIGN 
VARELT 
UNIQUELY 
INDEXEXT 
GENERCRT 
VALIDRTN 
REFORMAT 
' SPARE 
MAMECNT 
FLDPOSIT 
FLDLEN 
DFLDLEN 
ELTLIM 
DELTLIM 
ELTLEN 
DELTLEN 
VALIDARG 
NAMEFLD 
SECURITY 


FIELD 

TYPE 

FIELD 

FORMAT 

FIELD 

LOCATION 

FIELD 

LENGTH 

ELEMENT 

LENGTH 

ELEMENT 

GOTTMT 

LN 

A 

A 't ' 

A 

F 

F 

F ' • - 

t? 

0 

4 

4 

4 
15 
' 7 

0 

0 

0 

0 

0. . 

O 


A 

A 

A 

A 

A 

B 

B 

B 

B 

B 

B 

B 

B 

A 

A 

A 

HX 

SN 

SN 

SN 

SN 

SN 

SN 

SN 

SN 

A 

A 

A 


F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 

F 


4 
10 
11 

19 

20 
21 
22 
22 
22 
22 
23 
23 
23 

23 

24 


F 

32 

8 

F 

40 

8 

F 

48 

8 

F 

56 

2 

F 

58 

2 

F 

60 

- - 2 

F 

62 

2 

F 

64 

2 

F 

66 

2 

F 

68 

2 

F 

70 

2 

V 

1(2) 

52 

FE 

2(2) 

146 

FE 

3(2) 

]46 


6 

1 

8 

1 

1 

1 

0 ( 1 ) 

2 ( 1 ) 

4(1) 

6 ( 1 ) 

0 ( 1 ) 

2 ( 1 ) 

4(1) 

6 ( 1 ) 

8 


0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

8 

9 


C1) IZ w "“ ltChea the le “8>* field is used to indicate 
the bit location within the byte. 

(2) For variable length fields the location field is used 
as a variable field index. 


0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 

18 
16 . 



PAGE 132 


\" r v''' ' Ateiiiii f ; ., = .. UC .^- 0U tr-iic rs 

THE POSITION OF FIELDS SI1HIN ft FECCFD 

Fields are positioned in the data record in the order in 
which they are created as tc the following algorithim. On 
the anchor and associated files the order is? 

1. FECLEN, 

2. anchor file key field, 

3, record security field, 

*1, all packed bit fields, 

5* all fired length fields, 

6, all varying length and elemental fields. 

On subfiles the order by position is: 

1. RECLEN 

2, subfile key field, 

2 3* subfile parent key field, 

4, record security field, 

LX 5* all packed bit fields, 

L - . 6, all fixed lenatb Fields, 

3'. 7. all varying length and elemental fields, 

Th« Descriptor Editor maintains three lists of fields for 
each descriptor region, one list for each of the folloiwing 
field groups: 

packed tit fields, 

2. fixed length fields including ordinary or unpacked 
bit fields, 

3, varying length and elemental fields. 

The order within each field group is determined by the order 
in which the nser creates fields within each group. This 
ordering may be changed thrcuqh use cf the N07E command. 
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TCHC D.3 - DBIOAE USEB's GUIDE 


I. INTBCDUCTION 

The DBLOAD program is a generalised routine 
to be used for either initially loadina data 
onto a newly defined file, or fer updating 
an existing file. In either case, the 
descriptors for the file must have been 
completely specified by using the Descriptor 
Editor before any loadinq of data is attempted. 
The program is made general by the fact that 
each input record read is passed to a 
specifically written sub-routine which 
identifies each of the fields that comprise 
the record, and passes this information back to 
DBLOAD for processing. 

This manual describes the mode cf operation 
for DBLOAD, LINKEDIT for EBLOAE, and the 
parameters necessary to invoke it. The 
procedures to follow for writing a DBLOAD 
exit routine are also in this user’s guide. 

II. LINKEDIT 

Since every load will have its own user-written 
exit routine, it is necessary tc linkedit the 
new exit routine with other needed DBLOAD 
modules to produce the final executable DBLOAD 
module. A standard LINKEDIT deck could 
be made-up where all the user has to do is 
insert the INCLUDE card for his exit routine 
and then execute the LINKEDIT step. 

As a separate step after the LINKEDIT, the 
DBTABLE procedure must be executed. This 
puts the new external entry point name of 
the DBLOAD Exit routine into a dictionary 
file that is used by NASIS. 

Currently, the DBLOAD exit routine must be 
compiled with the PL/1 version f compiler to 
be compatible with DBLOAD. 

Appendix E gives an example of a LINKEDIT 
for DBIOAE, with the EETAELE step. 

III. INPUTS AND OUTPUTS 


DBLOAD Table 1 lists the maior inputs and 



PAGE 134 


outputs from the DBLOAD program, 
and produced (output) by the DELOAD 
program. 


INFO T INPUT DATA SET: This data set contains the 

data that is to be loaded to the output 
databases. The input must be an indexed 
sequencial data set. 

DATABASE DESCRIPTORS: This data set is the 

previously defined file descriptors for 
the database to be loaded. 

PARAMETER CONTROL CARDS: This data set 

contains the program paramets for 
different program functions. 

OUTPUT DATABASE: This is the actual files oabing 

up the database. Database can include an 
anchor file, associated files, subfiles, 
and indexed files. 

ERROR DATA SIT: This data set is a copy of 

the input records that cannct be loaded to 
the database. 

MESSAGE DATA SET: This data set contains 

error messages and ether informational 
messages (such as record counts) . 
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IV. 


STATEMENT 

JOE 

STATEMENT 

exe: 

STATEHBNT 


SISP8INT 

DD 

STAT EMENT 


PBTOUT 

DD 

STATEMENT 

CAFDIN 

DD 

STATEMENT 


EBE08 

DD 

STATEMENT 


CCNTBOL 

The DBICAD Program is controlled by lob control 
statements. The jot control statements are 
required to execute or invoke the DELOAD program 
and to define the data sets that are used and 
produced by the program. The parameter 
statements are used to control the functions 
of the lead. 

JOB CONTBOL STATEMENTS 

DB10AD Table 2 shows the lot control statements 
necessary for executing or working the DBLOAD 
program. 


DBLOAD Table 2. Job Control Statements for 
the DBLOAD program 

USAGE 

This statement initiates the job. 


This statement specifies tbe program name 
(PGM = DBLOAD) or, if the job control 
statements reside in a procedure library, the 
procedure name. 

This statement defines a sequencial message 
data set. 

The data set can be written onto a system 
output device, a magnetic tape volume or a 
direct access volume. (This DD statement must 
be present) 

This statement defines the informational data 
set written by the program. DCB = (BECFM=FA, 
LRECL=133, BLKSIZE= 133) . DDNAME fixed. 

This statement defines the parameter card 
data set that contains the program parameters. 
Data set resides in the input stream. DDNAME 
fixed. 

This statement defines the error data set that 
will contain records that cannot be loaded to 
The database. DDNAME is not fixed. 


DATABASE 


These statements define all files that are 
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DD in the database (descriptors, anchor, 

STATEMENTS associated, subfiles, indexes) . 

INKJT This statement defines the input data set 

DD that contains data to be leaded to database. 

STATEMENT Must be an indexed sequencial data set. 

DDNAME not fixed. 

STEP IIB This statement defines the library where the 
DD production or latest version of the EBLOAD 

STATEMENT module resides. 

STATIC This statement defines the STATIC (statistics) 
DD file. 

STATEMENT 

ESETAB This statement defines the external static 

DD dictionary entry points file. 

STATEMENT 
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PARAMETER STATEMENTS 

The DBLOAD program is controlled by 
parameter statements. The parameter 
statements are enterd in the input 
stream (CARDIN DD Statement) as required. 
Following is a list of DBLOAD proqram parameters 
with their functions: 

• filename* 

identifies the database to be loaded. 

Specified as: a 1-6 character name of 

the database. 

* mode* 

identifies the mode of operation for the 
program 

Specified as: a one character code, 

*L* for load mcde, ’O' for update mode, 
and *R* for restart mcde. 

Default: load mode is assumed. 


•exit • 

identifies the name of the user exit 
routine which is to be called to 
describe the composition cf each input 
record. 

Specified as: a 1-7 character name of 

the user exit routine entry point. 

Default: the exit name is constructed by 

prefixing the file name with an ’X*. 

•format • 

identifies the name of the key field 
reformatting routine. 

Specified as: a 1-8 character name whose 

first character must be alphabetic and 
whose remaining character must be 

alph anumeric. 


Default: no kev formatting routine is 

assumed. 

* anchor* 

indicates whether the anchor file is 
to be loaded 


Specified as: a one character code. 
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*Y* for yes, and * W* for no. 

Default: the anchor file will not be 

loaded. 

♦associate* 

identifies the associate files to be 
loaded. 

Specified as: a multiple element 

parenthesized list of associated file 
suffices (1,2,... 9) 

Default: no associated files sill be 

loaded . 

•subfile* 

identifies the subfiles to be loaded. 

Specified as: a multiple element 

parenthesized list of subfile suffixes 

(P»S|.. .) 

Default: no subfiles will be loaded. 

* index* 

indentifies the fields to be inverted 
with this load. 

Specified as: a multiple element 

parenthesized list of 1-8 character 
field names (P IELD1, FIZLD2, . . .) 

Default: no index files will be loaded. 

* input* 

identifies the fully qualified name of 
the input data set from which DBLOAD is 
to obtain its data. 

Specified as: a 1-35 character fully 

qualified dataset name. 

Default: no index files will be loaded. 

* input* 

identifies the fully qualified name of 
the input data sat from which DBIOAD is 
to obtain its data. 

Specified as: a 1-35 character fully 

qualified dataset name. 

Default: the input dataset name is 
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constructed by appending tbe qualifier 
♦.INPUT* to the file name, 

♦generate* 

indicates whether or not large numeric 
keys are to be generated for the output 
data base. 

Specified as: a one character code, * Y ♦ 

to indicate that large numeric keys 
are to be generated, and *N* to indicate 
not to generate keys. 

Default: Keys will not be generated. 

* error* 

identifies the fully qualified name of 
the error dataset to which invalid input 
records are to be dumped. 

Specified as: a 1-35 character fully 

qualified dataset name. 

Default: the error dataset name is 

constructed by appending the qualifier 
* . ERROR * to the file name. 

* errors* 

identifies the number of non-critical 
data errors that are allowed before 
terminating the program 

Specified as: a 1-4 digit number. 

Default: a limit of ICO errors is 

established . 

Examples: 

1. The user wants to load a file with the 
anchor, associated file 1, subfiles 
¥ and Z, The key has a formatting 
routine entry point name of DBEMTLN, 

No fields are to be inverted. User 
exit routine is XEXIT and input file 
DSNAME is filename, input. Appendix A 
illustrates a run deck for above load. 

V. OPERATING MODE 

A. Load Mode 

In the load mode, EE1CAD simply opens the 
input dataset for input and the file for 
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output and feeqins processing. 

B. Update Mode 

In the update mode, DBICAD opens the 
input file for incut and the output file 
for direct output and begins processing. 

C. Restart Bode 

In restart mode, DBIOAE opens the file for 
update. It uses the restart key to position 
itself in the input dataset. It then 
reads the next sequential record. It is 
now ready to heqin processinq. 

DBLOAD EXIT FOUTIHES 

A. Introduction 

As mentioned earlier, DBICAD passes each 
input data record to a user written exit 
routine for analysis before actually 
writing any data to tie file. This 
routine has the function of identifying 
each data field in the input record with 
a field name, indicating its starting 
location in the inout record, and 
specifying the lencrth of the data. If 
the data field is on a subfile, the exit 
routine has to identify the subfile control 
field name before any subfile fields can 
be put. 

Further, the routine can specify that 
the field should have leading and/or 
trailing blanks stripped off by DBLOAD, 
that the field be skipped, that the record 
be skipped, that the load be terminated, 
or that subseouen t calls tc the exit 
routine must indicate when a new key is 
to be located to the output file. This is 
used in the case of multiple input records 
for an output file key. 

When the update mode is used, the exit 
routine must indicate if this is a record 
to fce deleted, a record to be added, or 
a record to te replaced, 

B. Exit Routine Parameters 

The calling sequence used by DBICAD to 
transfer control to the exit routine is: 
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CALL exitname (input-data, user-ptr. 

bypass- switches) 


Where: 

'exitname* 

is the entry point name of the routine 
to be called. 

♦ in put- data * 

is a varying length character string 
(max ilium sixe - 4000 bytes) that 
contains the entire input data record, 
includincr the fcur-bvte record length. 

'user ptr* 

is an external pointer that points 
to the user allocated structure. 

This structure contains the field 
names, the field lengths, the field 
offsets, and the subfile suffixes. 

'bypass -switches * 

is a strina of sixteen bit switches 
to be posted by the exit routine to 
further define the status of the record 
for DBLOAE. The order and meanings of 
the various bits are: 

Bypass Call - bypass subsequent calls 
Bypass Record - bypass this record 
Forward-Scan - deiete leading blanks 
on fields 

Backward-Scan - delete trailing 
blanks on fields 

Terminate Pgra - terminate the program 
Delete-Record - delete this record 
Replace-Record - replace this record 
Opdate-Secord - update this record 
(fields) 

New-Key - locate this new key 
Bits 10-16 - unused by DBLOAD 

Exit Routine User Structure 

The following sample exit routine (appendix 

illustrates how to declare and use the 
user based structure. First, set the 
refer dimension equal to the maximum 
number of fields and elements (one field 
and a multi-element field with 10 elements 
would be 11) plus number of subfile control 



PAGE 142 


fields that may be assigned. 

Next allocate the based user structure. Next 
assign the key-name, the key-ptr to the 
location of the key within the input record, 
and assign the key field length. Each 
entry into the exit routine will then 
reauire the field names to be assigned, 
the record, the field sixes assigned, 
and the subfile suffixes assigned if 
field is a subfile control field. 

NOTES: 

1. The Key of the input record can be 
anywhere in the record. 

2. The input data record includes the 
record length field. 

3. Larqe numeric keys can be generated for 
the output dataset if desired. 

4. The number of elements in the user 
structure is computed by accumulating 
the total number of fields and/or 
elements in the input record. 

5. Any field whose length is zero or 
whose pointer is null, is bypassed. 

If subfile suffix is not blank, new 
subfile record is located. 

D. Sample DBLOAE EXIT Boutine 

The following sample exit routine is 
shown to illustrate the above narrative. 

The field has a key, one anchor file 
field, and two subfile fields with two 
elements each. The fields are all in 
fixed locations. After initial allocation, 
the only processing required is to scan a 
record type field for the code •X* which 
is used to indicate tc bypass this 
record. Note that all trailing blanks 
will be stripped off and that every 
input record is a new key and will have 
an output record located for it. The 
subfile control field »KID* has a field 
size of zero. The sub-suffix byte for 
this field gets assiqned a * Z* to indicate 
this is a subfile control field. 


VII 


loading Multi-files 
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For the most efficient use cf DBLOAD, it should 
be noted that whenever possible, NC field 
should be inverted while file is being loaded. 
The DBPAC inversion process is extremely 
faster to load an entire file and then 
invert the desired fields with the inversion 
utility, invert. This module uses specialised 
techniques and an OS sort utility to build 
the index files. 

Subfiles should never be loaded independently of 
the anchor file, however. EBPAC must generate 
the subfile keys and post the subfile control 
field for each subfile record. 
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//CCCBDG 
//IB LOAD 
//STEPLIB 
//SYSPBINT 
//m BOR 
// 

// 

DCE= (DSORG 
// 

//IN POT 
// 

// 

// 

//FILE$$ 

//niB$i# 

//file$$i 

//FI LE$$Y 

//nn$$z 

//STATIC 
//KDTAB 
//CAR IIN 


/* // 


APPENDIX A 
SAMPLE JOB DECK 

JOE <9350,SYST,06Q) ,NECTERICS 
EXEC PGM-DBLCAE, BEGI0N=800K 
DD DSN=NASIS. JCBIIB,DISP=SHF 
DD SYSOOT= A 

DD DSN=FXIENA ME. EFBOB , 0NIT=231 4 
VOI-SEB=WOBK01,DISP=(NEN,KEEP) , 

IS,BECFM=V,IFECL=4QG 1,B1KSTZE=4005, 

RKP=5,KEYLEN=4,OPTCD=L) ,SPACE= (CYl, (3,1) ) 
DD DSN=FILINAHE. INPUT, ONIT=2314, 
VOI=SER=HORK01,DISP=CID,DCB= (DSOBG=lS, 
RECFM=V,IRECI=4001,BIKSIZE=4005,EKP=5, 
KEYLEN=4) 

DD DSN=NASIS.FIIE$$FIIE$$,DISF=SHR 
DD ESN- NAS IS FILE$$. FILE$$# , DISP=SHR 
DD DSN=NASIS.FIIE$$.FIIE$$1,DISP=SHB 
DD ESN=NA SI S. FILE$$. FIIE$$Y ,DISP=SHB 
DD D5N=NASIS. FILE$$. FILB$$Z , DISP=SHB 
DD DSN=NASXS. STATIC, DISP=SHF 
DD ES N 1 NASIS. LC A DT AB , DISP-SHR 
DD * 


MODE=L 

EXIT=XEXIT 

FORMAT=DBFMTIN 

ANCBOB=Y 

ASSOCIATE 

S0EFIIB= (Y,Z) 

INPUT=FILENAME. INPUT 

FILFNAMI=FILE$$ 
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APPENDIX B 
LINKEDIT FOE DBICAD 


//CCCBDGLK 

//IKED 

// 

//SYSPBINT 

//SYSLI8 

// 

// 

//BASIS 

//SYSLHOD 

//SYSDT1 

// 


JOE (9350, SY ST, 01 5) , NFCTEBICS ,REGION=132K 
EXEC PG8=IEWL , 

PABM='XBEF, LIST, LET, SIZE= (150K,40K) * 

DD SYSOUT=A 

DD DSN=NASIS.JCBLIB,DISP=SH5 
DD DSN-ANSIS. TESTLIE, EISP=SHB 
DD DSN=SYS1.PL1LIB,DISP=SHB 
DD CSN=ANSIS • OEJLIB, DISP=SHB 
DD DSN=NA SI S« TEST I,IE (IB LOAD) ,DISP=SH5 
DD DSN=6RSYSCTl,nNIT=SYSD£,SPACE=( 1024, 

(200) 20) ) , SEP= (SYSLMCD ,SYSIIE) , CCB=ELKSIZE= 
1024 //SYSLIN EE * 

INCLUDE NASIS (DBCALL ,DBLCAD , PHTFILE , FP ABM , 
DERPAC) 

INCLUDE NASIS (DBUPDST , DBDBI0 , JNEXITS , 
DBEXITX , DBBTNS ) 

INCLUDE NASIS (EXITBTN) 

ENTBY IHENTBY 


/* //CBTABLE EXEC DBTABLF , MODUIE=DBICAD, MCDL IE= JOBLIB, 

// ESETAB=LOADTAB 

//BU NETAB. SOBTOUT DD ECB=NASIS. ESDTAE 

// 
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APPENDIX C. 

/* XEXIT: TEST EXIT SOUTINE FOP FEBLOAD FOB THE FILE 

DBWTDB */ 

/* COMPANY: NEOTERICS CORPORATION, CIEVEIAND, OHIO 

V 

*/ 

/* CLIENT: NASA LEWIS FESEAFCH CFNTEF 

V 

/* SYSTEM; NASA AEROSPACE SAFETY INFORMATION SYSTEM 
(NAS IS) */ 


/* THIS IS A SAMPLE EXIT ROUTINE FCF DBIOAD FOR DB2. 

IT */ 

/* SHOWS HOW TO USE THE OSEF STRUCTURE TO ASSIGN FIELD 
NAMES, FIELD */ 

/* OFFSETS, AND FIELD SIZES . IT AISC SHOWS HOW TO USE T’HE 
EXIT */ 

/* SOUTINE SWITCHES TO ACCOMPLISH VARIOUS OPTIONS TO THE 
LOAD. */ 

XEXIT: PROCEDURE (INPUT_CATA , USEE_PTP , BYPASS_SWITCHES) ; 

/* DECLARE BUILT IN FUNCTIONS USED BY EXIT 

*/ 

DCL (NULL, ADDR) BUILTIN : 


*/ 


*/ 

*/ 

*/ 


DCL INPUT_DATA CHAF(4000) VAF; /* INPUT FECORD 
DCL USEF^PTR POINTER; /* USER POINTEE 

DCL BY PASSES WITCHES CHAR (2) ; /* PROGRAM SWITCHES 


/* 

OPTIONS 

DCL 

SWITCHES 

TO EXIT 

*/ 

BIANKS 

TRAILING 

*/ 


DECLAFE SPECIAL SWITCHES FOP PROGRAM 

*/ 


1 SPECIAL^ SWITCHES BASED (SW_PTR) ,/* SPEC PROGRAM 
*/ 


2 BYPASS^ CALL BIT (1) , 

*/ 

2 BYPASS_RECORE BIT(1), 
2 FORWARD SCAN BIT(1), 

*/ 

2 EACKWARD_SCAN BIT(1), 
BLANKS */ 

2 !EFHINATE_PGK BIT(1), 


/* SKIP FUTURE CALLS 
/SKIP THIS RECORD 
/* STRIP OFF LEADING 
/* STRIP OFF 


/ABORT THE LOAD 
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2 EELET F_RECORD EIT(1), 

/* 

DELETE THIS 

RECORD 

♦/ 





2 REPLACE RECORD EIT(1) 

/* 

REPLACE THIS 

RECORD 

♦/ 





2 OPDATE_RECORD BIT (1) , 

/* 

ADD THIS RECORD 

*/ 


2 NEW KEY BIT (1) , 

/♦ 

IOCATE THIS NEW 

KEY 


*/ 





2 SPECIAL_FILL BIT (7) ; 

/♦ 

UNDEFINED 

*/ 

DCL 

ON BIT (1 ) STATIC INIT(M»B); 

/* 

ON BIT SWITCH 

*/ 

DCL 

OFF BIT ( 1) STATIC INIT('0»E); 

/* 

OFF BIT SWITCH 

*/ 

DCL 

ONE_TIME CHAR ( 1 ) CONTROLLED; 

/* 

ONE TIME SWITCH 


/* DECLARE USEE STRUCTURE TO BE ALLOCATED 

BY EXIT */ 

/* ROUTINE AND DO THE FOLLOWING: 

*/ 

/♦ AND CONTFOI FIELD AND ELEMENTS TO EE PUT */ 

*/ 

/♦ 2. ASSIGN FIELD NAMES* 

*/ 

/* 3. ASSIGN FIEID POINTERS TO OFFSET IN INPUT 

RECORD */ 

/♦ 4. ASSIGN FIELD SIZES, 

*/ 


DCL 1 

USER : 

STRUC BASED <USER_PTB) , 

/* 

USER BASED 

STRUCTURE 

V 




2 

DIM FIXED BIN (15) , 

/* 

DIMENSION OF 

ARRAYS 

*/ 





2 

FEY_NABE CHAR (8) 

/* 

KEY NAME 

*/ 






2 

KEY^PTR PTR, 

/* 

KEY POINTER 

*/ 






2 

KEY_SIZE FIXED BIN (15) 

,/* 

KEY SIZE 

*/ 






2 

ITEMS (DIM.REFER RFFFR 

/* 

REFER DIMENSION 

FOR ARRAYS 

*/ 






(USER STRUC. IIM)) 

/* 


V 






3 

FIELD_PTB PTR, 

/* 

FIELD POINTER 

*/ 






3 

FIELD_SIZE FIXED BIN (15) , 

/♦ FIELD SIZE 

*/ 






3 

SCB SUFFIX CHAR (1) ; 

/♦SUBFILE 

SUFFIXlFIRST SUB 

- *7 






/* 

FILE SUFFIX IS 

CTRL FLD 

*/ 





DCL DIH_REFEB FIXED BIN (15); /* REFER DIMENSION 
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TO BE ASSN */ 


/• 

V 


DCL PTR 1 POINTER; 
RECORD */ 

DCL SW_PTR POINTER; 
SWITCHES ~ */ 


DECLARE EXIT ROUTINE FCINTERS 

/* POINTER FOR BASED 
/* POINTER FOR 


/* 

*/ 


DECLARE RECORD OVERLAY 


DCL 1 FECCRD_IN BASED (PTR 1), 


/* RECORD OVERLAY 


*/ 

2 

BLTH 

CHAR (4) , 

/* 

RECORD LENGTH 


2 

RFILL 

CHAR (3) , 

* ; 

FILLER 

V 

2 

EMPNO 

CHAR (4) , 

/* 

EMPLOYEE NUMBER 

*/ 

2 

RTYPE 

CHAR ( 1) , 

/* 

PECORD TYPE:IF 

•x* 

TEEN 

*/ 


/* 

SKIP THIS RECORD 

*/ 

2 

EMPNAME 

CHAR (20) , 

/* 

EMPLOYEE 

NAME 

STRIP OFF */ 







/* 

TRAILING BLANKS 

V 

2 

EHPAGE 

CHAR (2) , 

/* 

EMPLOYEE AGE 

*/ 

2 

KIDNAME1 

CHAR (10) , 

/* 

KIDNAME_STRIP OFF 

V 

2 

KIDNAME2 

! CHAR (1 0) 

/* 

TRAILING BLANKS 

*/ 

2 

KIDAGE1 

CHAR (2) 

/* 

KIDAGE_STRIP OFF 

*/ 

2 

KIDAGE2 

CHAR (2) ; 

/* 

TRAILING BLANKS 


*/ 

PTRl = ADDS (INPTJT_DATA) : 

*/ 

SW PTR=ADDR(BYPASS_SWITCHES) ; 
*/” 

IF ALLOCATION (ONE_TIME) THEN 
ALLOCATED ”*/ 

GOTO CHECK_RECORD; 

*/ 

ALLOCATE ONE TIME; 

SWITCH */ 

DIK_BEFER_8; 

MAXI BOM */ 

CONFRL */ 

ALLOCATE USEB_STRUC; 

*/ 


/* SET RECORD POINTER 
/* SET SWITCHES POINTER 
/* IF USER STROC 
/* GO AND CHECK RECORD 
/* TORN ON ONE TINE 
/* SET DIMENSION TO 
/* NUMBER OF FIELDS, 

/* FIELDS, AND ELEMENTS 
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DIM =DIM REFEB; /* ASSIGN TO DIM IN STBUC 

V 

KEY_ NAM=* EMPNO* ; /* ASSIGN KEY NAME 

*/ ~ 

KEY_PTB=ADDR (EHPNC)/* SET KEY FOINTER */ 

KEY SI2E=4; /* ASSIGN KEY SIZE 

V ~ 


FIELD_NAHE{1) = ♦ENFRAME*; 

V 

FIELD_NAME(2)= , EMP»GE»; 

*/ 

FIELD NAME <3) = ♦ KID* ; 

V 

FIELD NAHE(4)=»KIENAME»; 

FIEL D~NAME (5) =*KICAGE»; 

FIELD NAME (6) = *KIE * ; 

*/ 

FIELD NAME(7) =«KIDNAMF»; 

FIIL D*NAME (8) =*KIDAGE f ; 

FIEL D_PTR ( 1) =ADDR (EHPNAME) ; 

*/ 

FIELD PTR<2)=ADDR (EMPAGE) ; 
FIEL D~PTR (3) ■= NULL ; 

PTF */ 

FIILD_PTR (4) = ADDR (KIDNAME1) ; 
FIEL D_PTR (5) = AEDR (KID AGE 1) ; 
FIEL D~PTR (6) =NULL; 

PTB */ 

FIELD PTR (7)=ADDR (KIDNAHE2) ; 
FIELdIpTR(8)=AEDR(KIDAGE2? ; 

FIEL D_SIZE (1>=20: 

SIZES */ 

FIELD SIZE { 2) =2; 

fieldIsize<3)=0; 

?IELD_SIZE(4) =10; 

FIEL D^SIZE (5) = 2; 

FIEL D_SIZB(6) =0; 
FIELD_SIZE(7)=10; 

FIELD~SIZE (8) =2; 

S0E_S0FFII{1) =* •; 

SUFFIX */ 

SDE_SUFFIX<2)=* *; 
S0E_S0FPIX{3) = *Z* ; 

RECORD */ 

SUE_SDFFIX(4) =» •; 

S UE~ SUFFIX ^5) =* *; 

SDE_ SUFFIX < 6) = *Z« ; 

RECORD V 

SU£_SUFFIX<7)=* * ; 


/* ASSIGN FIELD NAMES 

/* 

/* SUB RECORD ONE 
/* SUE RECORD TRO 

/* ASSIGN FIFLD OFFSETS 
/* NOIL CONTROL FIELD 

/* NOIL CONTROL FIELD 

/* ASSIGN FIELD 

/* ASSIGN SUBFILE 
/* SUBFILE Z 

/* SUBFILE Z 
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SUE_SUFEIX<8) «* *; 

EYPASS_CALL=OFF; 

*/ 

FORW ABD_SCAN=OFF ; 

LEADING~BLANKS */ 

BACKHARD_SCAN=ON; 

BLANKS ♦/ 

TERMINATE PGH-OFF; 

LOAD ~ */ 

DEIET E_R£CCRD=OFF; 

*/ 

REELACE_RECOBD =OFF; 

UPIA T E_RECORU=OFF ; 

NEN KEY=ON; 

*/ 

DISPLAY ('USER STRUCTURE ALLOCATED IN EXIT ROUTINE.*); 


RETURN; 

V 

/* 

RETURN TO DBLOAD 

CHECK RECORD: 
V 

/* 

CHECK RECORD TYPE 

IF RTYPE= * X ' 

*/ 

/♦ 

IF X RECORD TYPE, 

THEN BYPASS RBCORD=ON; 

*/ 

/* 

BYPASS THIS BECORD 

ELSE BYPA5S_RECORB=OFE; 

*/ 

/* 

OTHERWISE, PROCESS IT 

RETURN; 

♦/ 

/* 

RETURN TO DBLOAD 

END; 

*/ 

/* 

END OF ROUTINE 


/* SILL CALL EXIT ROUTINE 
/* DON'T STRIP OFF 
/* STRIP OFF TRAILING 
/* DON'T TERMINATE THE 
/* NOT AN UPDATE RUN 

/* LOCATE THIS RECORD 
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TOPIC D. 4 - INVERSION PROGSAN USEB*S GUIDE 

I. INTRODUCTION 

The NASIS inversion program is two maintenance 
programs (DBIVRT1, DBIFPT2) and an OS sort utility 
for data base file creation. The purpose of 
the programs is to take data ficm certain fields 
of a database and to post this data to an 
inverted index file. This operation can be done 
automatically by DEPAC during a normal file loading 
operation, but it is very time consuming and could 
therefore leopardize the successful completion 
of the load. Further, ty separating this function 
out, in this manner, the capability of creating 
inverted indices after a file has been loaded and 
used is added to the repertoire of the NASIS 
system. Finally, this separation also permits 
the use of specialized technigues suitable 
specifically to this furction tc reduce the amount 
of time required for the entire process c£ loading 
and index creation. 

This manual describes the mode cf operation, 
invoking DBSIVRT, gives examples of use, and 
gives additional program notes. 

II. NODE OF OPERATION 

The inversion module can create up to ten inverted 
index files concurrently. Further, these files 
can each contain data from up to five separate 
but related fields. The user can process a 
specific number of input records, a range of 
input records, or the entire file. Restart 
capability is provided at the field reading 
step, the sert step, the index file creation 
step, and the index file translation step. 

Step one (invert 1) reads a dataplex, strips off 
the field being inverted, concatenates the field 
with the anchor key, and writes the concatenated 
string on a seguencial data set. 

The second, or sort step, invokes the OS sort 
utility and outputs a sorted sequential file. 

Step three (invert 2) reads the sorted variable 
data set and creates a CISAN file. If the field 
is not indexed with external format, this file 
becomes the database index file. 

If the field is indexed with external format 
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step three reads the QISAH file created by step 
three r translates the keys with field formatting 
routine, and creates translated index file. 

III. INPUTS AND OUTPUTS 

INVEST Table 1 lists the major inputs and 
outputs from the INVERT 1 program, 

INVERT Table 2 lists the major inputs and 
outputs from the INVERT2 program. 

IV. CONTROL 

The INVERT programs are controlled by job control 
statements and parameter statements. The job control 
statements are required to execute or invoke the 
INVERT programs and to define the data sets that 
are used and produced bv the programs. The 
parameter statements are used tc control the 
functions of the inversion. 

JOB CCNTFOL STATEMENTS 

INVERT table 3 shows the job control statements 
necessary for executing or invoking the INVERT 
process. 

PARAMETER STATEMENTS 

The INVERT process is controlled by parameter 
statements. The parameter statements are entered 
in the input stream (CARLIN DD Statement) as 
required. Following is a list cf INVERT proqram 
parameters with their functions; 

•FILENAME* 

identifies the database that the field being 
inverted is on. Specified as a 1-6 character 
name. 

•field* 

identifies the field (s) to be inverted. 

Specified as; a 1-8 character name as 
entered in the file descriptors. Multiple 
fields must be entered as multiple element 
list. Fields being inverted to same index 
file must be kept toqether. 

Example; (A 1 , A2,A3 ,B1 ,E2 ,C) First three 
fields go on same index file, fields B1, 

B2 go cn same index file, field C goes on 
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index file by itself, 
mode • 

identifies the proqram mode of operation. 

Specified as: a one character code, 

F - initial pass, step one 
F - restart at step one 

3 - restart at step three (Step after Sort) 

T - restart at translation phase of step 3 

Default: the initial pass (*F*) is assumed. 

records* 

identifies the number of database records 
to process. 

Specified as? 1-6 numeric characters. 

Default: 999,999 records (or entire dataplex) , 

range* 

identifies a range of file keys to process. 

Specified as: a multiple element list of 

two file keys, first key being the one to 
start at, second kev being the one to end at. 

Example: (KET05,KIY10) Keys 5-10 will be 

inverted. 

Default: Entire file is assumed. 
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INVEST Table 1. Eata sets used (input) and 
produced (outputs) by the INVERT 1 program* 

INPOT DATABASE: These data sets contain the data to 

be inverted. The descriptors are also needed 
to define the data fields. 

PARAMETER CONTROl CARDS: This data set contains 

the program parameters for different proqram 
functions. 

RESTART FILE: This data set is needed if 

program is invoked in restart mode, to 
provide a restart Key. 

OUTPOT OUTPUT FILE: This data set is a CSAH file 

with the value of the field being inverted 
concatenated with the file Fey. This file becomes 
the input to the OS sort step. 

MESSAGE DATA SET: This data set contains error 

messages and other informational messages (such 
as record counts) . 
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INVERT Table 2. lata sets used (inputs) and 
produced (outputs) bv the INVERT2 program. 

INPUT INPOT FILE: This data set is the sorted output 

from the OS sort utility step. 

DATABASE DESCFXPTOBS: This data set describes 

the database. 

PARAMETER CONTROL CARES? This data set contains 
the program parameters for different program 
functions. 

OUTPUT PLEX FILE: This data set is in the form of an 

index file with the internal field value as the 
Key. This file becomes the input to the 
translation routine to convert to the external 
form. Produced onlv if external indexing. 

RANGE FILF: This data set is the index file 

with the internal format. It is produced only 
if a range of file Keys was specified as a 
program parameter. 

DATABASE INDEX FILE: This data set is the final 

index file and is part of the database. 

MESSAGE DATA SET: This data set contains error 

messages and other inf ormaticnal messages (such 
as record counts) . 
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STATEMENT 

JOE 

STATEMENT 

EXEC 

STATEMENT 


STEP 1IB 
DD 

STATEMENT 

SYSPBINT 

DD 

STATEMENT 


P5TOCT 

DD 

STATEMENT 

CARDIN 

DD 

STATEMENT 


DATA EASE 
DD 

STATEMENTS 

FI IE 
DD 

STATEMENT 


PABH 

DD 

STATEMENT 

SOFT I N 
DD 

STATEMENTS 


PLK 

DD 


INVERT Table 3. Jcb Control Statements for 
the INVEST process. 

USAGE 

This statement initiates the icb. 


This statement specifies the program name 
(PGM=INVERT1) , (PGM-INVERT2) , or, for the 
sort utility, the sort procedure name (SORTD) . 

This statement defines the library where the 
production or current version of the INVERT 
modules reside. 

This statement defines a seguencial message 
data set. The data set can be written onto a 
system output device, a magnetic tape volume, 
or a direct access volume. (This DD statement 
must be present) . 

This statement defines the informational data 
set written by the program. BCB= (RECFM=FA, 
LRECL=133, BLKSIZE= 133) • DDNAME is fixed. 

This statement defines the parameter card 
set that contains the program parameters. 

Data set resides in the input stream. DDNAME 
is fixed. 

These statements define all the files that 
are in the database (descriptors, anchor, 
associated, subfiles, indices). 

These statements define the QSAM files that 
are output from step one. Numeric integer 
1-0 is concatenated to 'FILE' to make the 
appropriate DDNAME. Minimum IRECL is 18 
(DSORT utility) . 

LRECL is sum of file Kev length plus maximum 
field length. 

This statement defines the restart file for 
step 1. DCB = (RECFM^V, IRECL=255) , 

DDNAME is fixed. 

These statements define the sorted QSAM 
data sets from the sort step. Numeric 
integer 1-Q is concatenated to 'SORTIN' 
to make the appropriate DDNAME. 

These statements define the temporary 
index files with the internal field 
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STATEHENTS 


format. The DCE will be tie same as the 
final index file. 
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EXAMPLES OP USE 

The INVEST process may he set up as one job 
with three separate steps (INVEBT1 , SCBTD, 

INVEBT2) . If many fields are teinq inverted at 
one pass, however, it is recommended to split 
the three steps into separate jobs since these 
will he multiple sorts. 

The most efficient method is to invert as many 
fields as possible in the same pass. Database 
records cniy have to be accessed one time for 
multiple fields. The multiple sorts could then 
be set up as separate jobs. 

Invert all associated fields separate as one pass from 
anchor fields. This is very efficient because 
only the associated file is accessed. 

Example one shows two fields, ’EMPAGE' and 
* EMPNAME’ being inverted at the same time. The 
database, *1111$$* has a Key length of 4, Since 
the EMPAGE field is only two bytes in length 
the minimum, LRECL of 18 is used for the FILE1 
DD statement (2+4). The EMPNAME field is varying 
with a maximum length of 16, therefore, LBECL of 
20 is used for FILE2 DD statement (4 ♦ 16). 

Step 2 is an example of the IBM OS sort utility, 

SOBTD. For further explanation, see IBM publication 
order no, GC28-6543-7, CS SOBT/MEBGE Program. The 
sort control card specifies the sort field to start 
in first position of record and qo for 6 bytes. 

The field is character and sort will be in ascending 
order. The size is 2C0 records. Note that if 
condition code from STEF1 is not less than 4, STEP2 
will not be run. Only sort for the EMPAGE field 
is shown, sort for EMPNAME field would be similar. 

Step 3 builds the final index files for the 
EMPAGE and EMPNAME fields. Note that if the 
sort step passes a condition code greater than 3 
step 3 will not be run, A plex DD statement is 
needed for the EMPAGE field because of external 
indexinq. The two INDEX DD statements catalog the 
index file entries after successful completion of 
the run. Note the MODE parameter is *3* for 
step 3. 

Note that all data sets are deleted upon 
successful completion of job step. Only final index 
files for database should be kept. 
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IF range of Keys had teen specified, final 
output index file would have a DSNAHE of RANGE. 
FILE$$. FIELDNAME. This data set is then used to 
meroe with ether range index files, 

//EXAMPLE1 JOE (9350, SYST,C15) , NECT1RICS 
//ST EP 1 EXEC IGH=INVERT1, BEGIOK=500K 

//STEPLIB DD DSN*NASIS. JOBLIB ,DISP=SHR 

//SY SPRINT DD SYSCUT=A 

//PRTOUT DD SYSOOT=A, DCB* (BECFM*F A , LPECL* 1 33 , 

BIKSIZEJ=133) // DI# DD 

DSN* NASIS. FILE$$ . FILE$$ #, DISF=SHB 
//CD DD DSN=NASIS.FILE$$. FILE$$, DISP=SHR 

//IDA DD DSN=NASIS. FILE$$.FILE$$A» DISP* 5 HR 

//DD B DD DSN*NASIS. FILES*. FI1 E$$B, DISP=SHR 

//FI I El DD DSN=SORTIN.FILE$$.E8PAGE,UNIT*2314 

// VOL*SEF=WORK01, DCB* (FECFM=E E, LRECL* 18, 

// BLKSI2E*36Q0) , SPACE* (CYI , 3) , DISP* (NEW , 

KEEP, DELETE) //FIIE2 CD 

DSN* SORTIN.FILE$$.EfiPNA BE, UNIT* 2314, 

// VOL=SEB=HORK02 , DCB* (RECFM*FB, LRECL=20 , 

// BLKSIZE=4000) ,SPACE= (CYL, 3) ,DISP=(NEN, 

KEEP, DELETE) //CAB DIN ED* 

FIIENABE=FILE 

FIELD* (EWPAGE, EMPNAKE) 

HODE=F /* 

/ 

//STEP2 EXEC SCBT D, REGION* 98 K , CGNC=(4, LT) 

//SO RT.SORTIN DD DSNAME*SOBTIN.FILB$$. EMEAGF, 

// UNIT 2314,V0L=SER*W0RK01,ECE= {RECFM=FB, 

// LRECL*18, BLKSIZE=3600) , DISP* (CID , DELETE, 

KEEP) //SORT . SOBTCUT EE 
DSNA ME=SORTOOT. FILE$$ . EM PAGE , 

// ONIT*2314,YOL=SEB*W08K02, DISP* (NEW, KEEP, DELETE) , 

// 

SPACE*(CYL,3) , DCB* (RECFM=FB, LBECL*18 , ELKSIZE* 3600) 
//SORT.SORTWK01 DD 0NIT=23 14 , SPACE* (TBK, (10> , ,CONTIG) 

//SO BT. SORTNK02 DC UNIT* 2 3 14 , SPACE* (TBK, (10) , ,CONTIG) 
//SORT.SORTHK03 DD 0NIT=2314, SPACE* (TFK, (10) , ,CONTIG) 
//SJRT.SORTHK04 DD DNIT=23 1 4 , SPACE* (TBK, (10 ) , ,CONTIG) 

//SO BT.SOBTWK05 DD UNIT* 23 1 4 , S PACE* (TBK, ( 10) , , CONTIG) 
//S0BT.S0BTNKC6 DD UNIT | 23 14, SPACE* (TRY, (10) , , CONTIG) , 

// SEP* (SORTNKO 1 , SOBTNK02, SOETWK03 , SORTHK4, 

// SORTNK05) 

//SORT.SYSIN DD * 

SORT FIELDS* ( 1 ,6 ,CH, A) ,SIZE=20G 

/* 

//STEP3 EXEC PGM=INVEBT2,BEGICN=5C0K,CCND=(4,LT) 

//ST SPRINT DD SYSCUT=A 

//STEPLIB DD DS N=N A SIS • JOBLIB , DISP* SHB 

//PaTOOT DD SYSOOT=A, DCE= (F 1 CFM*FA , LRFCL* 133, 

/ / BliKSI^E 22 133) 

//DD# DD DSN* NAS IS. FILE$$. FILE$$#, DXSP*SHR 
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DD DSN=N AS IS. FILES $. FILEI!,DISP=SHB 
DD DSN^SOBTOUT. FIIE$$.EWPAGE, 

DISP= (CLD, DELET E, KEEP) ,ONIT=23 14,DCB= 
(BECFM=FB r LBECL=18,BLKSI2E=360C) , 
?OL=SEB=WOBK02 //SCRTIN2 DD 
SOBTOOT. FIIE$$. E8PNA0E, EISP= 

(OLD, DELETE, KEEP) , UNIT=23 14 , DCB= (BECFE=FB, 
LBECL=20,BLKSIZE=4000) , VOi=SEB=NOBK02 
EX1 DD DSN=PLEX.FILE$$.EHPAGE,DISP= (NEB, 

DELETE) , UNIT* 23 14, ECB= (ESOBG=IS, RBCFE=V , 
LBECL=40Q1,BLKSIZE=4QC5,GFTCD=I,BKP=5, 
KEYLE8*2) , SPACE= (CYL, (3,1) ) , YOI-SEB=BOBK0 1 
DEX1 DD DSN=NASIS. FILES! A, 0NIT=2314,£ISP=(NE9, 

CATLG, DELETE) r DCB- (DSCBG=IS,BECFf*=V , 
LBECL=4001,BLKSIZE=4005,RKP=5,KEYLER=2, 
OPTCD=L) , SPACE 3 (CYL, (3,1)) ,VC1=SEB=FDA01 1 
DEX2 DD DSN=NASIS. FILE$$. FIL E$$B, 0NIT=23 1 4 , 

DISP= (NEB, CATLG, DELETE) ,DCE= (CSOBG=IS, 
BECFM=V,LBECL=400 1,ELKSIZE=4005,RKP=5, 
KEYLEN-16,OPTCD=L) ,SPACE= (CYL, (3, 1) ,VOL= 
SEB=FDA01 1 
BEIN DD * 


//CD 

//S0RTIN1 

// 

// 


DSN= 

// 

// 

//PL 

// 

// 

// 

//IN 

// 

// 

// 

//IN 

// 

// 

// 

// 

//CA 


FILENAME = FILE 

FIELD = (EBPAGE, EEPNAHE) 

MODE = 3 



PAGE 161 


TOPIC D. 5 - INDEX MERGE PROGRAM USER'S GUIDE 

I. INTRODUCTION 

The merger program (DBINDM) is a special program 
for the merging of index files. The purpose of 
the program is to take two index files (created 
from a like data base) and merge them to a new 
index file or inplace to the accepted current 
index file. Further, the user is given the 
options to process duplicate list elements. 

This manual describes the mode of operation for 
DBINDM, the parameters used tc invoke DBINDM, 
gives examples of its use, and gives additional 
program notes, 

II. INPUTS AND OUTPUTS 

DBINDM Table 1 lists the major inputs and 
outputs from the OBINDM program, 

DBINDM Table 1. Data sets used (input) and 
produced (output) by the DBINDM program. 

INPUT COBRENT INDEX FILE: This data set, contains the 

current database index lists. 

UPDATE INDEX FILE: This data set contains the 

new or update postings to be merqed with current 
index file. This data base is usually created 
by the INVERT program and has a ESNAKE of 
•RANGE. 'FILENAME. FIELDNAME. 

DATABASE DESCRIPTORS: This data set provides 

information about the field that is indexed. 

OUTPUT UPDATED INDEX FILE: This data set is the 

updated inplace version of the index file. 

NEH INDEX FILE: This data set is the new 

merged index file created from the current 
index file and the update index file* The 
DSN AME is 'INDMRG. 'FILENAME, FIELDNAME. 

MESSAGE DATA SET: This data set contains 

error messages and inf crmaticnal messages 
(such as record courts) . 

III. CONTBOI 

Tlhe DBINDM program is controlled by job control 
statements and parameter statements. The job 



PAGE 162 


control statements are required to execute or 
invoke the DBIHDH program and to define the 
data sets that are used and produced by the 
program. The parameter statements are used 
to control the functions cf the index merge. 

JOB CONTROL STATEMENTS 

DBINDM Table 2 shows the jet control statements 
necessary for executing or invoking the DBINDM 
program • 
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ST ATE BENT 
JCE 

Statement 

EXEC 

St at ement 


SYSPRINT 

DC 

Statement 


PRTODT 

DC 

Statement 


CARDIN 

DC 

St at ement 


DATABASE 

DD 

Statements 

RANGE 

DC 

Statement 


INEMRG 

DD 

Stat ement 

STEPLIB 

DD 

Stat ement 
IV. 


EBINDB Table 2. Job Control Statements for the 
DBINDW Proqram 

OSAGE 

This statement initiates the lob. 


This statement specifies the procrram name 
<PGH=DBINDB) or, if the job control 
statements reside in a prccedore library, 
the procedure name. 

This statement defines a sequential message 
data set. The data set can be written onto 
a system output device, a magnetic tape 
volume, or a direct access volume. (This 
DD statement must be present.) 

This statement defines the informational 
data set written by the pregram. DCE= 
(RECFB=FA, LRECL= 1 33 , BLKS IZE= 1 33) . DDNAHE 
is fixed. 

This statement defines the parameter card 
data set that contains the proqram 
parameters. Data set resides in the input 
stream. DDNABE is fixed. 

These statements define the database 
descriptors, and the current database 
index file. 

This statement defines the update index 
file tc be merged with the current index 
file. DSNABE must be 
•RANGE.* FI LEW ABE. FIE ID BABE. 

This statement defines the new merqed 
index file. The DSNABE is 
* INDMRG. * FILENABE . FIELDNANE . 

This statement defines the library where 
the latest version of the EBINDB proqram 
resides. 

BODE OE OPERATIONS 

EBINDB can create a new inverted index 
file, or it can merqe inplace to the 
current inverted index file. This is 
done at the discretion of the user. 
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V, INVOKING DBINDM 

PARAMETER STATEMENTS 

The EBINCM program is controlled by 
parameter statements. The parameter 
statements are entered in the input stream 
(CARDIN DD Statement) as required. 
Following is a list of DBINDM program 
parameters with their functions: 

•FILENAME* 

identifies the database with the 
index file beina merged. 

Specified as, a 1-6 character name 
of the database. 


•Mode' 

identifies the program mode of 
operation. 

Specified as: a one character code, 

* F * - FI1STPASS 
*R» - RESTART 

DEFAULT: NONE. 

• Model * 

identifies the target merge file. 

Specified as: a one character code, 

*1* - New File 
•0* - Inplace 

• Field* 

identifies the master inverted index 
field. 

Specified as: 1-8 character name as 

entered in the file descriptors. 

•Mode2* 

indicates if duplicate list elements 
will be processed or not. 

Specified as: a one character code, 

*1* - Process Duplicates 

•O' - No Duplicates Processed 


VI 


EXAMPLES 

Following is an example of the icb control 
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statements required to invoke DBINDM. The 
user wants to merge index file APOLLOA with 
FANGE . APOLLO . KEYWORDS and create a new index 
file with duplicates being processed. Field 
value is 4 bytes lcng. 


//EX ABPLE1 

JOB 

(935C,SYST,060) ,NECTEBICS 

//STEP1 

EXEC 

FGM=DBINDM,BEGICN=800K 

//ST E PL IB 

DD 

DSN=NASIS. JOBLIB,DISP=SHB 

//SYS FBI NT 

DC 

SYSOOT=A 

//PB TOOT 

DD 

SYSOOT A, DCB= (BECFfi=FA , 1BECL=1 33 , 

// 


ELKSI7E=133) 

//DD$# 

DD 

DSN=NA SIS. APOLLO. A FOLIC#, DISF= SUB 

//DD$ 

DE 

DSN=NASIS. APOLLO. AFOLLCA, DISP=SHB 

//FANGE 

DD 

DSN=BANGE. APOLLO. KEYWORDS , DISP=SHB 

//INDMBG 

DD 

DS N= INDMBG. APOLLO. KEYWORDS , 

// 


ONIT=2314,VOL=SEH=WCBK01 , 

// 


EISP=<NEW, KEEP, DELETE) , DCB= (DSOBG=IS , 

// 


BECFM=V,LBECt=4001 , BLKSIZE=4 005 , 

// 


FKP=5,KtYLEN=4,OPTCC=L) , 

// 


SPACE= (CYL, (3,1)) 

//CABDIN 

DD 

* 


FILEMAKER APOLLO 
MODE = F 
MODE 1=1 
KCDE2=1 

FIELD=KEYHORDS /* 

// 

VII. PHOGBAM NOTES 

A. If the user wishes to merge inplace, 
he first must make a copy of the 
current index file (for security 
reasons) . 

B. The input or update index file to 
be merqed is named 

BANGE. FILENAME. FIELDNAME. Check 
this before processing is bequn. 

C. Nhen merging to a new file, the new 
file being created is called 
INDMBG. FILENAME. FIELDNAME. 

D. After the new file is created and 
checked, it should replace the current 
index file, and the current index 
file should be erased. 
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TOPIC D 
I. 


II 


INPOT 


OOTPOT 


III. 


.8 - MAINTENANCE OSEB*S GUIDE 
INTBODUCTIGN 

The maintenance program (DEMNTN) is an independent 
module to be used for maintaining the NASIS 
system database. This maintenance will consist of 
additions to. deletions from, modifications of the 
data contained on a database. The data to be 
used to describe the desired changes will take 
the form of transactions and will be obtained 
from the transaction database (TBNSCT) • The 
transactions can reference a particular record, 
field or element in describing the desired 
change. 

Maintenance, as designed, will always fee run 
ncn-conversaticnally . It must be run under the 
userid of the owner of the database being 
maintained. The program is restartable in that, 
each transaction processed successfully, is 
deleted from the transaction database. 

This manual describes the operating procedures, 

the mode of operation, and the types of transactions 

supported. 

INPUTS AND OUTPUTS 

DBBNTN Table 1 lists the major inputs and 
outputs from the DBBNTN program. 

DBMNTN Table 1. Data sets used (inputs) and 
produced (output) by the DBMNTN program. 

DATABASE: These data sets are the files that 

make up the database including the descriptors. 

TBNSCT FILES; These two data sets are the 
anchor transaction file and the TBNSCT file 
descriptors. 

DATABASE: These data sets are the files of the 

database that will be updated. 

MESSAGE DATA SET: This data set contains error 

messages and other informational messages (such 
as record counts) • 

CONTROL 

The DBBNTN program is controlled by job control 
statements. The job control statements are 
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required to execute or invoke the DBMNTN 
program and to define the data sets that are 
used and produced by the program. The PASH 
statement is used on the EXEC card to define 
the database being maintained. 

JOB CONTROL STATEMENTS 

DBMNTN Table 2 shows the lob control statements 
necessary for executing or invoking the 
DBMNTN program. 

DBMNTN Table 2. Job Control Statements for the 
DBMNTN Program 

STATEMENT USAGE 

JOE This statement initiates the lob. 

STATEMENT 

EXEC This statement specifies the program name 

STATEMENT (PGM=DBHNTN) or, if the job control statements 
reside in a procedure library, the procedure. 

The PARM function must be used with 
appropriate database name. (PAFM = *FILE$$*) 

This statement defines a seguencial message 
data set. The data set can he written onto 
a system output device, a magnetic tape 
volume, or a direct access volume. (This 
DD statement must be present) . 

PETOUT This statement defines the informational 

DD data set written by the pregram. DCB= (B£CFM= 

STATEMENT FA,IEECL= 133, BLKSIZE=133) DDNAME is fixed. 

DATABASE These statements define all the files that 
DD make up the database (descriptor, anchor, 

STATEMENTS associated, subfile, index). 

TRNSCT These statements define the TRNSCT (transaction) 

DD file and the TRNSCT file descriptors. 

STATEMENTS 

ST EP L IB This statement defines the library where the 

DD production or latest version of the DBMNTN 

STATEMENT module resides. 

STATIC This statement defines the STATIC (statistics) 

DD file. 

STATEMENT 


SYSPRINT 

DD 

STATEMENT 


IV 


MAINTENANCE OPERATING PROCEDURES 
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In preparing to run maintenance on a database, the 
Database administer should perform a preliminary 
step. He may use the CORRECT command to peruse 
the transactions and to delete any which he 
deems to be unnecessary or invalid (See CORRECT 
command Oser*s Guide). 

Once the transactions are determined tc be 
acceptable, he is ready to initiate maintenance. 
Bestart is similar, but should require no 
transaction editing, 

V. MAINTENANCE MODE OF OPERATION 

The database is opened for update, the transactions 
are opened for update and processing begins. 

Each transaction is handled separately and if 
successfully processed, the transaction is deleted. 

VI, EXAMPLES 

Following is an example of the lob control 
statements to initiate the DBMNTN program: 


//IX AMPLE 1 

//STEP1 

//STEPLIB 

//SYSPHINT 

//PR TOUT 

//DDl# 

//ED* 

//TRNSCT# 

//TRNSCT 

//STATIC 

// 


JOB (935C,SYST,06C) , NEOTEFICS , REGION: 800 K 
EXEC PG?f=DBNNTN,PARM=*fItI*$* 

DD DSN=NASIS. JOBLIB,DlSP=SHR 
DD SYSCUT= A 

DD SYSOOT=A,DCB= (RECFM=F A , I RECL=1 3 3 , BLKSIZE= 1 33) 
DD DSN=NASIS.FILE*$. FILE**# , DISP^SHF 
DD DSN-NA SIS. FILES*. FILE$I,DISP= SHF 
DC DSN=NASIS. TRNSCT. TRNSCT #, EISP= SHF 
DD DSN=N ASIS. TRNSCT. TRNSCT, EISP=SBR 
DD DSN=NASIS. STATIC, DISP=SHR 
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TOPIC E. 1 - TSPL/I LANGUAGE EXTENSION 


I. INTRODUCTION 

The terminal support preprocessor for NASIS {TS) allows 
the PL/I programmer to include in his program, 
statements, in normal PL/I syntax, which refer to and 
use the various terminal support functions. To enable 
the use of the TS preprocessor in a particular program, 
it is only necessary to insert the following 
statement: 

% INCLUDE LISRMAC(TS); 

This statement must appear before any actual use of the 
preprocessor itself. 

The preprocessor functions available are listed in the 
appendix alcrg with the terminal control block fTCl 
containing the various switches and ccntrcl fields that 
are used by terminal support. The functions provided 
perform a set of generalized operations on the terminal 
device. These operations can be altered and refined by 
the setting of appropriate switches in the TC block 
before invoking the particular TS function. This 
alteration is most useful for the PUT and PROMPT 
operations. 

In addition to the functions listed, terminal support 
has defined two interrupt conditions, ATTN and END, to 
facilitate programmer ccntrol cf the terminal device. 
The ATTN condition is raised each time the user 
depresses the attention kev on his terminal, when this 
occurs, terminal support calls the last defined PL/I ON 
block for ATTN • s via the signal mechanism. If the ON 
block returns, terminal support will prompt the user 
for a command with the following message: 

-ATTN: 

The user may respond tc this messaqe with any of the 
"immediate" commands: 

SYNONYM 

SYNONYMS 

DEFAULT 

DEFAULTS 

PFOFILE 

EXPLAIN 

PROMPT 

STRATEGY 

KA 
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KF 

BACK 

END 

APOFF 

GO 

A default response is interpreted as a GO. If during 
the execution of one of these commands, the user 
depresses the attention key, that command will be 
terminated and the user will he reprompted. 

The user may define an ON ATTN block in his proqram, 
but he must adhere to the following restrictions: 

1, He may only issue output TS functions. 

2. If he wants to suppress the system prompt, he 

must branch out of his ON block (by so doing, 
he cannot return to the point of 

interruption) . 

If the user wishes to disable attentions completely, he 
must set the ’DISABLED* bit in the system data table 
USERTAB. (This action should only be taken in the most 
critical situations) . 

In the above description, if the user had responded 
with an END command, terminal support would have raised 
the END condition via the signal mechanism. The 

purpose of this condition is to provide a standard 
method of terminating a proqram or application and yet 
allowing it to perform any "clean-up** actions that are 
necessary. As with ATTN, any output TS messages will 
be allowed. 

The terminal support functions assume that the device 
has a screen, and that this screen is divided into an 
upper output area and a lower prompting area. The 
logical dimensions of the screen are defined by the 
physical dimensions or the default values for the 
symbols SCRNHGT and SCENHTH . The current dimensions of 
the screen can be found in the TC block during the 
execution of the program. 

STATEMENTS 

A. ENABLE < ATTN | END | *ALL>; 

This statement causes the default coding for the 
END and/or ATTN conditions to he generated into 
the program. The default code for ATTN is to 
simply return to the point of interruption. The 
default code for END is to branch to a rontine 
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that will terminate the program via a RETURN. 

This statement, if present, must appear only once 
in the proqram and before any ENTRY statements. 
This statement also implies an ENTRY statement, 

B. ENTRY; 

This statement must be executed before any other 
TS statements, during a particular invocation of 
the program. It establishes the default ON 
blocks generated by ENABLE and calls terminal 
support to initialize the TC block. Because of 
its function, an ENTRY statement should appear at 
each entry point cf a proqram, or at a common 
point in the processing for all entry points. 

An ENTRY need not follow an ENABLE, as the ENABLE 
statement includes and implies ENTRY. 

C. ON PAGE CALI {entry) ; 

This statement establishes the name of the routine 
which is to process pacing of the screen for the 
current function. Nhen a function has filled the 
screen with data and terminates with more data to 
be displayed, a PAGE command will result in a call 
to the entrv point specified by the most recent ON 
PAGE statement. 

The "entry" parameter must be, or will be, 

converted to a character string of eight or fewer 

characters in length, 

E. PROMPT MSG (key) COSING (inserts) > <INTO (buffer) > ; 

This statement has two functions, the outputtinq 
of a message (where the INTO clause is omitted) 

and prompting for a command. The message 

specified will be located in the message library 
and displayed to the user. Any inserts specified 
will be placed in the proper positions within the 
text before it is displayed. If the roessaqe 
cannot be found, terminal support will 
automatically issue a diagnostic containing the 
messaqe key. If a command prompt is indicated, 
the text will be preceded by a dash (-) and a 
string of ("tr :") will be appended to it before it 
is displayed. All inserts will be stripped of 
leading and trailinq blanks. nnspecified inserts 
will be replaced by "***«. 

The "key" parameter must be, or will be converted 
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to a character string of eight or fewer characters 
in length. The "inserts" parameter must he a list 
of twenty or fewer character strings. The 
"buffer" parameter must he a character string into 
which the command entered is to be placed. It 
should be eight characters in length, or 
greater* 

If the command entered fcy the user, after synonym 
search, will not fit in the string specified by 
the user, TC. PROMPT. TRUNCATION will be turned on 
by terminal support. Further, this, or any other 
type of error (syntax, etc.), will cause 
TC. PROMPT. ERROR to be turned on. 

PROMPT KSG (key) <USING (inserts) > KEYWORD (id) 

INTO (buffer) ; 

This statement is used to request parameters 
and/or data from the user cr from the profile. 

The "key" parameter must be, or will be converted 
to a character string of eight or fewer characters 
in length. The "inserts" parameter must be a list 
of twenty or fewer character strings. The "id" 
parameter must be, or will be converted to, a 
character string of eight or fewer characters in 
length. The "buffer" parameter must be a 
character string into which the data is to be 
placed. The maximum size data element returned by 
terminal support is 255 characters. 

If the TC. PROMPT. BYPASS tit is turned on by the 
user prior to this statement, terminal support 
will examine the remaining parameters in its 
buffer and the profile for the data value, but 
will not prompt the user. Otherwise, if no value 
is found in the buffer or in the profile, the user 
will he prompted for the data value. If the "id" 
parameter is null and the data is specified in 
keyword format, terminal support will post the 
keyword into TC. PROMPT. KEYWORD for the user* If 
the program detects an invalid data value and 
wishes to reprompt the user for it, the 
TC. PROMPT. ERROR bit should be turned on prior to 
the PROMPT* If any errors are encountered by 
terminal support, the TC . PROMPT. ERROR bit will be 
turned on. If the data entered will not fit into 
the string specified, the 1C. PROMPT. TRUNCATION bit 
will be turned on. If the value returned was 
obtained from the user’s profile, the 
TC. PROKFT. DEFAULT bit will be turned on. 
Likewise, if the value returned was a quoted 
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string, the quotes will be removed and the 
TC. PPCHPT. STRING bit will be turned on. If the 
value returned is an element of a parenthesized 
list, only the element will be returned, and the 
TC, PF0MPT.MO5E__DATA bit will be turned on. 
Subsequent prompts will result in succeeding 
elements fceinq returned, until the end of the list 
is reached. 

F. READ INTO (buffer) ; 

This statement causes the current contents of the 
screen to be returned to the user. 

The "buffer" parameter must be a character string 
into which the data is to be placed, 

G. SPITE FFCM (buffer) ; 

This statement causes the screen to be written 
from the area specified, without any editing. 

The "buffer" parameter must be a character string 
which contains the data to be written. 

H. POT CLINE 1 PAGE> FROM (buffer) CTAG (value) > 
CFOPSAPD | BACKWAFD>; 

This statement causes a new record to be placed 
into the screen buffer. 

The "buffer" parameter must be a character string 
which contains the data to be written. The 
"value" parameter must be a character string which 
is to be used to identify this output record, if 
LINE is specified, the record is sequentially 
added to the screen buffer. If PAGE is specified, 
the screen buffer is reset and this record becomes 
the first record of the new screen. The FORWARD 
and BACKWARD opticns are used to control the 
direction of the sequential filling of the screen 
buffer, from the top down, or from the bottom 
up. 


If the user’s data exceeds the width of the 
screen, the seccnd and subsequent lines begin at 
the position indicated by TC.OOTPtJT. INDENT. If 
the user’s data causes the screen to overflow, 
the amount of data written is indicated by 
TC.ODTPUT. WRITTEN. If the user wishes only 
complete records to be written to the screen, he 
should have TC.OUTF UT. PtJT_PARTIAL turned of f. If 
the user wishes the screen to be automatically 
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written when the buffer is filled, he should turn 
on the TC. OUTPUT. AUTO_«RITE hit. If the user 
wishes to have his lines split between words (for 
text processing) he should turn on the 
TC. OUTPUT. WOFD_BREAK bit. If the user has 
displayed a segment of the current record on the 
previous page and he wants the remaining segment 
tagged and/or indented, he must turn on the 
TC. OUTPUT. CONTINUATION bit. If the last PUT 
caused the buffer to be filled, the 
TC. OUTPUT. OVERFLOW will be turned on. 

I. FIUSH; 

This statement is used to force the contents of 
the screen buffer tc be written, even though it is 
not filled. If the user wants tc indicate that 
more data remains to be displayed via the paqinq 
mechanism, he should turn on the 
TC. OUTPUT. MORE^DATA bit before his last output 
operation. 

J. FINISH? 

This statement causes the preprocessor to generate 
the necessary code to enable execution time 
communication with terminal support. It must be 
the last TS statement in the program. 
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TOPIC G,1 - TJSAGE STATISTICS 


I. INTRODUCTION 

Osage Statistics is, essentially, a separate sub-system 
of NASIS, whose function is tc collect and retain 
statistics, conceiving the use and status of the 
system. The statistics maintained are divided into 
retrieval statistics, use cf the system, and 
maintenance statistics, states of the data. The 
retrieval statistics include counts of the number of 
times that various commands have been invoked, the 
number of retrieval sessions, the dates and time used 
for those sessions, as well as the aggregate time spent 
retrieving data. The maintenance statistics include 
counts of the numbers of record additions, deletions 
and updates, for the anchor file, subrecord files and 
for all inverted index files. 

The maintenance of these statistics is an automatic 
function and will not be discussed here. Shat will be 
covered by this document is the production and use of 
the reports available through Osage Statistics. It 
should be noted that the retrieval statistics are 
available to any NASIS user, while the maintenance 
statistics are available to the owner of the dataplex 
only. 

II. STATISTICS CHECKPOINT 

The statistics gathered for retrieval are maintained on 
a per session basis, with a capacity for thirteen 
sessions before re-initialization is necessary. 
Because of this, a check is made each time a new 
session is begun, and if re-initialization is 
necessary, a checkpoint listing of the retrieval 
statistics is produced, so that the data on file will 
not be lost. 

The checkpoint report is a formatted list of the data 
cn file for a particular NASISID, before 
reinitialization. It will contain a line entry for 
each of the sessions on record, displaying the command 
counts, the lines, the date, the file name, and other 
pertinent information. The DEA should examine this 
report to analyze the usage that NASISID is making of 
the system and of the individual dataplexes. If he 
deems that some action is necessary, e.q., a user is 
loqged onto the system for excessive periods of time, 
but not executing many commands, he should do whatever 
he feels is required. In any event, the report should 
be retained for future reference and analysis, and 
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should probably be filed by NASISID. 

A sample checkpoint report is included in Figure 1. 

III. RETRIEVAL STATISTICS REPORT 

By submitting JOB CCCRPBNTR, the status of the entire 
retrieval satistics file can be presented. This report 
displays the activity of the various RASISIDS, the 
various data bases and the various retrieval 
commands. 

The retrieval report is formatted by WASISID, with a 
line entry for each terminal session. These entries 
present the various command counts, the lines, the file 
names, and other pertinent information. In addition, a 
summary is made, at the end, of the aggregate times and 
sessions for all users. 

A sample retrieval report, is included in Figure 2, 

IV. KAINTENANCE STATISTICS REPORT 

By submitting JOB CCCRFRTM, the status of the entire 
maintenance statistics file can be presented. This 

report should be used by the DBA to validate the 
maintenance records of each data base. In addition, it 
should be used to assess the maintenance activity of 
the various dataplexes. tfith this information, the DBA 
will be in a better position to know the exact status 
of his dataplexes, when to backup the system, when to 
reorganize his files, and many other questions that 
must be answered in order to maintain proper control 
over the system and its data. 

The maintenance report is formatted by dataplex name, 
with a line entry for each maintenance run. These 
entires present the counts of the number of additions, 
deletions and updates made to the anchor and associated 
files, the subrecord files and the inverted index 
files. In addition, a summary is made, for each file 
showing the aggregate and the averaqe number of 
additions, deletions and updates to the dataplex. 

A sample maintenance report is included in Figure 3. 
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DATAPLEX TOTAL ANCHOR 
NAME TRNS RECORDS 

ASRD1$ 3,132 


NUMBER TRANS MAINTENANCE FILEPLEX SUBPLEX 

RUNS RUN DATES ADDS DELETES UPDATES ADDS DELETES UPDATES 

1 12/19/72 3,132 


XPLEX 

ADDS DELETES UPDATES 

. l i . 


FILEPLEX ADDS DELETES ' UPDATES 


TOTAL 3,132 FOR ALL RUNS 


AVERAGE 


3,132 


PER RUN 



RETRIEVAL STATISTICS • . 01/03/73 


NASISID CONN-TIME 

CPU-TIME' ' 

// 

STRAT 

STORED 

OWNER 

FILE 

FIELD 

ACTUAL 

TOTAL 

NUMBER 

OF 

HR:MM:SC 

HR:MM: SC:MS 

SES 

LENGTH 

If 

ID 

NAME 

NAME- 

EXP 

SEL 

SRCH 

CORR 

NE01 0:53:30 

0:00:48:790 

5 

0 

0 

SAOWNER 

ASRD1$A 

AUTHOR 

3 

i 

0 

0 

0 






SAOWNER . 

ASRD1$B 

KEYWORDS 

13 

. 0 

0 

0 






SAOWNER 

DB2TDBA 

EMPAGE 

1 

0 

0 

0 






SAOWNER 

DB2TDBB 

TOTALCAR 

’ : i 

0 

0 

0 






SAOWNER 

DB2TDBC 

KIDAGE 

i 

0 

0 

0 


■ i ‘ 




SAOWNER 

DB2TDBD 

Ret ■ 

i 

0 

0 

0 






SAOWNER 

DB2TDBE 

SVCDATE 

i 

0 

0 

0 



LISR ID .CONN- TIME 
HR:MIN:SC 


NEOl 


:19:40 


SNAPSHOT (CHECKPOINT) OF RETRIEVAL STATISTICS RECORDS 

12/18/72 


BEFORE REINITIALIZATION 


CPU-TIME //' STRAT 
HR:MN!SC:MS SES LENGTH 

0:00:12:399 2 


OWNER- ID 
SAOWNER 


field 

NAME . 


FILE SESSION 
NAME . DATE 


KEYWORDS ASRDI$B 721215 
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EXPANDS SELECTS SEARCHS CORRECTS 


721215 

721215 

721215 

721215 

721215 

721215 

721215 

721215 

721215 

721215 

721215 


721215 1 


1 


-4 



